📂 Project vs. global

New here? A skill lives in a folder named after it, containing the `skill.md`. This folder can go in two places: inside .claude/skills/ INSIDE a specific project — it only exists for those who open that project — or inside ~/.claude/skills/, the user’s personal folder (`~` means “your user folder,” like Documents or Downloads)—available in ANY project you open later.

Think of it this way: the project folder is the desk drawer in that specific office—only the people who work there can see what’s inside. Your personal folder is the backpack you carry everywhere—what’s in it stays with you in every office you enter.

Caption: on the left, the project skill only lights up the project where it lives (the others stay dim). On the right, the global skill lights up all projects equally—it comes along wherever you open the agent.

A project skill is for a process specific to THAT client or repository — something that doesn't make sense outside that context. Example: "how to generate THIS client's monthly report" (with its spreadsheet format, PDF layout, and exclusive business rules). If you open another project, that skill doesn't even appear — and that's how it should be, because it wouldn't be useful there.

A global skill is for a process you repeat in ANY of your contexts—it doesn’t matter which project you’re in. A real example from this course itself: the "formato-curso-v2" skill, used to build this entire learning path, is global—it works for any INEMA course, not just wat7d. Another example: "how to write an email in my voice"—your voice doesn’t change from project to project, so the skill shouldn’t be tied to any one of them.

The choice involves three real trade-offs. Maintenance: a global skill needs to be generic enough to work in multiple places — if you make it too specific (mentioning a file or rule from a single project), it BREAKS when used in another. Portability: a project skill travels with that project’s `git` repository (anyone who clones it gets the skill); a global skill stays only on your machine unless you manually copy it somewhere else. Organization: the global folder grows over time and becomes your “personal toolbox” — more on that in topic 5.

Over time, your folder ~/.claude/skills/ you’ll accumulate global skills — one for creating a project guide, another for email tone, another for reviewing code, another for creating videos. That’s expected, and it’s good: you’re building a toolbox that spans all your projects. The same point from module 3.4 applies here — clearly differentiated descriptions keep the toolbox from becoming a mess of skills competing with one another.

# Skill de PROJETO — só existe abrindo esta pasta
meu-projeto-cliente-x/
  .claude/
    skills/
      relatorio-mensal-cliente-x/
        skill.md

# Skill GLOBAL — disponível em qualquer projeto
~/.claude/
  skills/
    formato-curso-v2/
      skill.md
      references/
    tom-de-email-pessoal/
      skill.md

Every decision in this module comes down to the same question, asked before creating a new skill: “is this process only for this project, or does it apply to any project I open?” The answer takes you straight to the right folder — no guesswork.