📁 As duas pastas
Novo aqui? Uma skill mora numa pasta com o nome dela, contendo o
`skill.md`. Essa pasta pode ficar em dois lugares: dentro de .claude/skills/
DENTRO de um projeto específico — só existe pra quem abrir aquele projeto — ou dentro de
~/.claude/skills/, a pasta pessoal do usuário (o `~` significa "sua pasta
de usuário", igual a Documentos ou Downloads) — disponível em QUALQUER projeto que você abrir depois.
Pense assim: a pasta de projeto é a gaveta da mesa daquele escritório específico — só quem trabalha ali vê o que tem dentro. A pasta pessoal é a mochila que você carrega pra todo lugar — o que está nela, está com você em qualquer escritório que você entrar.
Legenda: à esquerda, a skill de projeto só ilumina o projeto onde mora (os outros ficam apagados). À direita, a skill global ilumina todos os projetos igualmente — ela vem junto onde quer que você abra o agente.
🏢 Quando usar skill de projeto
Skill de projeto serve pra processo específico DAQUELE cliente ou repositório — coisa que não faz sentido fora dali. Exemplo: "como gerar o relatório mensal DESTE cliente" (com o formato de planilha, o layout de PDF e as regras de negócio exclusivas dele). Se você abrir outro projeto, essa skill nem aparece — e está certo que seja assim, porque ela não serviria pra nada lá.
🔍 Por dentro
- Portabilidade: a skill viaja JUNTO com o `git` do projeto — quem clona o repo, ganha a skill também.
- Especificidade permitida: pode citar nomes de arquivo, formato exato, regra de negócio única — sem medo de "quebrar" em outro lugar, porque ela não vai pra outro lugar.
🌍 Quando usar skill global
Skill global serve pra processo que se repete em QUALQUER contexto seu — não importa em qual projeto você está. Exemplo real deste próprio curso: a skill "formato-curso-v2", usada pra montar esta trilha inteira, é global — ela serve pra qualquer curso INEMA, não só o wat7d. Outro exemplo: "como escrever um e-mail no meu tom de voz" — seu tom de voz não muda de projeto pra projeto, então a skill não devia morar presa a nenhum.
✨ Dica Prática
Regra de bolso: se você consegue imaginar usando essa mesma skill num projeto totalmente diferente do atual, sem trocar nada, ela é candidata a global. Se qualquer frase da skill cita algo único deste projeto, ela é de projeto.
⚖️ Manutenção e portabilidade: o trade-off
A escolha carrega três trade-offs reais. Manutenção: skill global precisa ser genérica o bastante pra servir em vários lugares — se você a deixa específica demais (citando um arquivo ou regra de um só projeto), ela QUEBRA quando usada em outro. Portabilidade: skill de projeto viaja com o `git` daquele projeto (quem clona ganha ela); skill global fica só na sua máquina, a menos que você a copie manualmente pra outro lugar. Organização: a pasta global cresce com o tempo e vira sua "caixa de ferramentas pessoal" — mais sobre isso no tópico 5.
✓ Escolha certa
- ✓Skill "gerar guia de projeto" (global) — usada em todo projeto que você cria.
- ✓Skill "publicar release deste app" (projeto) — cita o pipeline exato daquele repo.
✗ Escolha errada
- ✗Skill global que cita "o arquivo `vendas_2026.xlsx` deste cliente" — quebra em outro projeto.
- ✗Skill de projeto pro seu tom de e-mail pessoal — some quando você troca de repositório.
🧰 A caixa de ferramentas pessoal
Com o tempo, sua pasta ~/.claude/skills/ vai acumulando skills globais —
uma pra gerar guia de projeto, outra pro tom de e-mail, outra pra revisar código, outra pra criar vídeos.
Isso é o esperado, e é bom: você está construindo uma caixa de ferramentas que atravessa todos os seus
projetos. O cuidado aqui é o mesmo do módulo 3.4 — descriptions bem diferenciadas evitam que a caixa de
ferramentas vire uma bagunça de skills concorrendo entre si.
Os dois caminhos de pasta, lado a lado
# 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🌳 A pergunta que decide
Toda a decisão deste módulo se resume a uma pergunta, sempre a mesma, antes de criar uma skill nova: "esse processo é só deste projeto, ou vale pra qualquer um que eu abrir?" A resposta te leva direto pra pasta certa — sem achismo.
Pergunta: "Esse processo cita arquivo, cliente ou regra de negócio ÚNICOS deste projeto?"
→ .claude/skills/ — skill de projeto.
→ ~/.claude/skills/ — skill global, entra na sua caixa de ferramentas.
Exercício — classifique estes 3 exemplos
- "Gerar a nota fiscal no formato exato que o sistema do Cliente Y aceita."
- "Revisar qualquer texto meu procurando erros de português antes de publicar."
- "Rodar o script de deploy específico deste repositório, com as variáveis de ambiente daqui."
Resposta esperada: 1 e 3 são de projeto (citam sistema/repo específico); 2 é global (serve pra qualquer texto seu, em qualquer projeto).
✨ Dica Prática
Na dúvida, comece de projeto — é mais fácil promover uma skill de projeto pra global depois (bastando generalizar o texto e mover a pasta) do que descobrir tarde que uma skill "global" só funcionava por acidente num projeto só.
Checagem rápida (opcional): qual pergunta decide se uma skill deve ser de projeto ou global?