Skill é uma pasta com um arquivo de texto dentro. Você escreve o procedimento uma vez, e ele para de precisar ser colado a cada conversa nova.
A diferença para o CLAUDE.md, escrita na documentação oficial: o corpo da skill
só carrega quando ela é usada. Enquanto ninguém precisa dela, ela não ocupa espaço
na conversa. O CLAUDE.md entra inteiro, sempre.
Onde a pasta vive
| Onde | Caminho | Vale para |
|---|---|---|
| Pessoal | ~/.claude/skills/<nome>/SKILL.md | Todos os seus projetos |
| Projeto | .claude/skills/<nome>/SKILL.md | Só aquele projeto |
Quando duas têm o mesmo nome, a pessoal vence a de projeto.
A primeira skill, em três passos
1. Crie a pasta
mkdir -p ~/.claude/skills/resumir-mudancas
2. Escreva o SKILL.md
---
description: Resume as mudanças não commitadas e aponta o que é arriscado. Use quando pedirem o que mudou, uma mensagem de commit, ou revisão do diff.
---
## Mudanças atuais
!`git diff HEAD`
## Instruções
Resuma as mudanças acima em dois ou três tópicos. Depois liste os riscos que
notar: tratamento de erro faltando, valor fixo no código, teste desatualizado.
Se o diff estiver vazio, diga que não há mudança não commitada.
3. Use
Digite /resumir-mudancas, ou simplesmente pergunte "o que mudou aqui?" — ele
carrega sozinho quando a descrição casa com o pedido.
O cabeçalho: só um campo é recomendado
Todos os campos são opcionais. O único recomendado é description — é por ele que
ele decide quando usar a skill.
---
name: nome-de-exibicao
description: O que faz e quando usar. Ponha o caso principal primeiro.
disable-model-invocation: true
allowed-tools: Read Grep
---
Os que mais rendem no dia a dia:
| Campo | O que faz |
|---|---|
description | Quando usar. Cortado em 1.536 caracteres na listagem — caso principal primeiro |
when_to_use | Frases-gatilho extras. Conta no mesmo teto de 1.536 |
disable-model-invocation: true | Só você chama. Para /commit, /deploy — coisa com efeito colateral |
user-invocable: false | Só ele chama. Para conhecimento de fundo que não é comando |
allowed-tools | Ferramentas liberadas sem pedir permissão, só no turno que invocou |
argument-hint | Dica no autocomplete, tipo [numero-da-issue] |
Quem chama: a decisão que evita susto
Por padrão os dois podem chamar. Dois campos mudam isso:
disable-model-invocation: true— só você. A documentação explica o porquê sem meias palavras: você não quer que ele decida fazer o deploy porque achou que o código estava pronto.user-invocable: false— só ele. Para convenção de API, padrão de código, coisa que é conhecimento e não comando.
Os limites que importam
- Mantenha o
SKILL.mdabaixo de 500 linhas. É recomendação da própria doc. Referência longa vai para arquivo separado na mesma pasta, carregado só quando precisar. - A descrição é cortada em 1.536 caracteres na listagem. Caso principal primeiro.
- O orçamento da listagem é 1% da janela de contexto. Com muitas skills, as que você menos usa perdem a descrição antes das outras.
Arquivos de apoio: o que faz a skill sair barata
minha-skill/
├── SKILL.md (o essencial — sempre que a skill roda)
├── referencia.md (detalhe — só quando precisar)
├── exemplos.md (só quando precisar)
└── scripts/
└── ajuda.py (executado, não lido para o contexto)
O SKILL.md fica enxuto e aponta para o resto. Especificação grande e coleção de
exemplos não precisam entrar no contexto toda vez.
Quando criar uma
A doc responde direto: quando você repete a mesma instrução, checklist ou
procedimento de vários passos — ou quando uma parte do CLAUDE.md deixou de ser
um fato e virou um procedimento.
Uma armadilha real
Uma vez carregada, a skill fica na conversa até o fim da sessão, e ele não relê o arquivo nos turnos seguintes. Então escreva como instrução permanente ("sempre faça X"), não como passo único ("agora faça X").
Documentação oficial: https://code.claude.com/docs/en/skills