Como criar sua própria Skill no Claude Code (passo a passo)

Se você já se pegou colando a mesma instrução gigante no Claude toda vez — "revisa meu commit assim, depois confere aquilo, no formato tal" — existe um jeito melhor. Chama-se Skill.

Uma Skill é uma pastinha com um arquivo de texto. Você escreve a instrução uma vez, e o Claude passa a usá-la sozinho sempre que a tarefa combinar. É a forma oficial da Anthropic de ensinar truques novos ao Claude — e dá pra criar a primeira em 10 minutos, sem programar.

Se você ainda não tem o Claude Code, começa pela instalação e depois volta aqui.

O que é uma Skill (sem complicar)

Pensa numa Skill como uma receita guardada. Em vez de explicar o passo a passo toda vez, você deixa a receita numa gaveta. Quando chega o momento certo, o Claude abre a gaveta, lê a receita e segue.

Tecnicamente, uma Skill é só uma pasta com um arquivo SKILL.md dentro. Esse arquivo tem duas partes:

1. Um cabeçalho (o "frontmatter", entre ---) que diz quando usar a Skill.
2. As instruções em texto comum — o que o Claude deve fazer.

Só isso. Sem instalar biblioteca, sem código obrigatório.

Por que não usar o CLAUDE.md?

Boa pergunta — porque os dois parecem parecidos. A diferença é quando cada um carrega:

• O CLAUDE.md é lido inteiro, em toda conversa daquele projeto. Perfeito pra fatos curtos e fixos ("a stack é Next.js", "sempre use pnpm").
• A Skill só carrega quando é relevante. O resto do tempo ela fica quietinha, sem ocupar contexto.

A regra prática: quando um pedaço do seu CLAUDE.md deixa de ser um fato e vira um procedimento (uma checklist, um passo a passo), transforme em Skill. Aquele texto longo passa a custar quase nada até a hora em que você realmente precisa dele.

Se você ainda não sabe o que é o CLAUDE.md, ele nasce do comando /init — explico no guia do Claude Code no terminal.

O segredo: disclosure progressivo

Aqui está a sacada de engenharia por trás das Skills (e por que elas escalam tão bem).

O Claude não lê todas as suas Skills o tempo todo. Ele funciona em três níveis, carregando informação só conforme precisa — a Anthropic chama isso de progressive disclosure:

1. Descoberta — ao iniciar, o Claude lê só o nome e a description de cada Skill. É pouquíssimo texto: o suficiente pra ele saber que a Skill existe e quando ela serve.
2. Ativação — se a sua tarefa casa com a description, aí sim ele lê o SKILL.md inteiro.
3. Execução — ele segue as instruções e, se a Skill tiver arquivos ou scripts extras, carrega só os que a tarefa exigir.

Tradução: você pode ter dezenas de Skills instaladas sem deixar o Claude lento ou "entupido". Cada uma só pesa quando entra em campo. É como um manual com índice — ele lê o capítulo certo, não o livro todo.

Onde a Skill mora

Você escolhe o alcance pela pasta onde salva:

O nome da pasta vira o comando. A pasta resumir-mudancas vira /resumir-mudancas. Simples assim.

A Skill de projeto tem um charme extra: como ela fica dentro do repositório, você commita junto com o código. Todo mundo do time (e todo Claude que abrir o projeto) ganha a mesma Skill de graça.

Mão na massa: sua primeira Skill em 10 minutos

Vamos criar uma Skill que resume o que você mudou e aponta o que parece arriscado.

Passo 1 — Criar a pasta

No terminal:

mkdir -p ~/.claude/skills/resumir-mudancas

Passo 2 — Escrever o SKILL.md

Crie o arquivo ~/.claude/skills/resumir-mudancas/SKILL.md com este conteúdo:

---
description: Resume as mudanças não commitadas e aponta o que parece arriscado. Use quando o usuário perguntar o que mudou, pedir uma mensagem de commit ou quiser revisar o diff.
---
 
## Mudanças atuais
 
Rode `git diff` e `git status` para ver o que mudou.
 
## Sua tarefa
 
1. Resuma as mudanças em até 5 bullets, em português claro.
2. Aponte qualquer coisa arriscada: segredo exposto, lógica
   removida sem querer, TODO esquecido, teste quebrado.
3. No fim, ofereça uma mensagem de commit curta no formato
   "tipo: descrição" (ex.: "fix: corrige cálculo do frete").

Repare: o description diz o que faz E quando usar, com frases-gatilho ("perguntar o que mudou", "mensagem de commit"). É por esse campo que o Claude decide carregar a Skill sozinho — então capriche nele. Ele é o mais importante do arquivo todo.

Passo 3 — Usar (das duas formas)

Abra o Claude Code dentro de um projeto com mudanças pendentes.

Deixe o Claude decidir. Pergunte algo que case com a description:

o que eu mudei aqui?

O Claude reconhece o pedido, carrega a Skill na hora e segue o seu roteiro. Você nem digitou o comando.

Ou force na mão, quando quiser o procedimento exato:

/resumir-mudancas

Pronto — sua primeira Skill está no ar. E o melhor: o Claude Code observa a pasta de Skills ao vivo. Editou o SKILL.md? A mudança vale na mesma sessão, sem reiniciar.

Campos úteis do frontmatter

O description resolve 90% dos casos. Mas tem outros campos opcionais que ajudam:

• name — nome de exibição na lista de Skills (por padrão, é o nome da pasta).
• disable-model-invocation: true — impede o Claude de carregar sozinho. Use pra Skills que você só quer disparar na mão com /nome. Ótimo pra fluxos perigosos, tipo um deploy.
• allowed-tools — lista de ferramentas que o Claude pode usar sem pedir permissão enquanto a Skill está ativa (ex.: Read Grep). Acelera Skills de leitura.
• argument-hint — dica de argumento que aparece no autocomplete, tipo [numero-da-issue].

Exemplo de uma Skill manual de deploy:

---
name: deploy
description: Faz o deploy da aplicação em produção
disable-model-invocation: true
---
 
Faça o deploy:
1. Rode a suíte de testes.
2. Se tudo passar, suba pra produção.
3. Avise o resultado.

Com disable-model-invocation: true, o Claude nunca vai fazer deploy por conta própria — só quando você digitar /deploy. Segurança por design.

Indo além: pastas de apoio

Quando o SKILL.md começa a ficar grande, não precisa empilhar tudo num arquivo só. A convenção da Anthropic é separar:

minha-skill/
├── SKILL.md          # instruções principais (curtas)
├── references/       # documentação detalhada, lida só quando precisa
├── scripts/          # código que o Claude pode executar
└── assets/           # modelos, exemplos, imagens

Mantenha o SKILL.md enxuto e aponte pros arquivos pesados em references/. Por causa do disclosure progressivo, esses arquivos extras só são lidos quando a tarefa específica exige — então você pode documentar à vontade sem medo de gastar contexto.

Por onde continuar

• O repositório oficial anthropics/skills tem Skills de exemplo prontas pra estudar — inclusive uma skill-creator que ajuda a montar as suas.
• Cadastra teu email lá em cima: a gente manda um pacote de Skills prontas pra você colar direto em ~/.claude/skills/ (code reviewer, otimizador de prompt, setup de MCP e mais). Dá pra ver a lista na página de Skills.
• Quer aprender a pensar como a Anthropic na hora de escrever instrução? Vale ler sobre o jeito que eles desenham com o Claude.

A ideia central é essa: tudo que você repete pro Claude pode virar Skill. Escreva uma vez, e ele lembra pra sempre — carregando só na hora certa.

Fonte: documentação oficial da Anthropic, Extend Claude with skills e Equipping agents for the real world with Agent Skills. Os fatos (caminhos, campos do frontmatter e o conceito de disclosure progressivo) vêm de lá; a redação, os exemplos e o passo a passo são deste blog.