Skills do Claude Code: como funcionam os skills, o SKILL.md e quando o agente os carrega

O que são skills no Claude Code

Um skill é uma pasta com um arquivo SKILL.md, que registra a instrução para um tipo específico de tarefa: como fazer o deploy do projeto, como conduzir uma revisão, como lançar uma release. O agente sabe da existência do skill desde o início da sessão, mas só lê o conteúdo inteiro quando a tarefa realmente exige.

Os skills do Claude Code resolvem um problema conhecido de quem mantém um CLAUDE.md por muito tempo: o arquivo de instruções cresce sem parar. Um procedimento de deploy de 80 linhas é necessário uma vez por semana, mas ocupa espaço no contexto de toda sessão — inclusive quando você só corrige um erro de digitação no README. O skill tira esses procedimentos do contexto permanente e os carrega sob demanda.

Do que um skill é composto

O skill mínimo é uma pasta e um arquivo. Os skills de projeto ficam no repositório; os pessoais, no diretório do usuário:

.claude/skills/deploy/SKILL.md      # skill do projeto, compartilhado pela equipe via git
~/.claude/skills/review/SKILL.md    # skill pessoal, disponível em todos os projetos

Ao lado do SKILL.md podem ficar arquivos auxiliares: modelos, scripts, materiais de referência. O agente os abre apenas se o texto principal do skill fizer referência a eles e se eles forem necessários:

.claude/skills/deploy/
├── SKILL.md           # instrução principal
├── checklist.md       # checklist detalhado, lido por referência
└── rollback.sh        # script de reversão

Frontmatter: name e description

O arquivo começa com um bloco YAML entre linhas ---. Dois campos são mais importantes que os demais: name — o nome curto do skill, e description — a descrição do que o skill faz e de quando aplicá-lo.

---
name: deploy
description: Deploy do site no hospedagem via FTP. Usar quando for preciso enviar alterações ao servidor, verificar diferenças com o servidor ou reverter um deploy.
---

# Deploy

1. Primeiro, uma execução de teste: `./deploy.sh -n`.
2. Conferir a lista de arquivos: não pode haver segredos nem scripts de teste.
3. Enviar: `./deploy.sh`.
4. Abrir as páginas alteradas e confirmar que respondem com 200.

Reversão — veja rollback.sh nesta pasta.

Abaixo do frontmatter fica um Markdown comum: passos, comandos, restrições, links para arquivos vizinhos. Escreva como escreveria uma instrução para um colega novo que vai fazer essa tarefa pela primeira vez.

Quando o agente carrega um skill

No início da sessão, entram no contexto apenas o nome e a descrição de cada skill disponível. São algumas linhas por skill, então dá para manter dezenas deles. Quando o pedido do usuário ou o passo atual do trabalho corresponde à descrição, o agente aciona o skill — e só então o texto completo do SKILL.md é carregado.

Disso sai a regra prática mais importante: o skill é acionado pela descrição. O agente não vê o corpo do skill até decidir abri-lo. Se a description diz «Skill auxiliar», o agente não entende quando ele é necessário. Se diz «Deploy no hospedagem; usar quando for preciso enviar alterações ao servidor ou reverter o deploy», ele entende.

Além da escolha automática, o skill pode ser chamado explicitamente pelo nome, com barra, por exemplo /deploy. Isso é útil quando você sabe exatamente qual procedimento é preciso e não quer depender de o agente associar o pedido à descrição.

Como escrever a description para que o skill seja acionado

• O que faz — em uma frase, com verbo: «Deploy do site», «Revisão das alterações antes do commit».
• Quando usar — liste as formulações que o usuário realmente usa para pedir a tarefa: «envie para o servidor», «publique», «reverta».
• Quando não usar, se o skill for fácil de confundir com um vizinho: «não é para deploy do bot, só do site».
• Evite termos vagos como «skill útil» e «ajuda no trabalho» — eles não trazem sinal nenhum.

Divulgação progressiva

Os skills são construídos sobre o princípio de divulgação progressiva (progressive disclosure): a informação é apresentada em camadas, e cada camada seguinte é carregada apenas quando necessária.

É a mesma ideia de um roteador no lugar de um muro de texto no arquivo de instruções: um mapa curto sempre à vista, e os detalhes por referência. A diferença é que o skill torna esse carregamento um mecanismo padrão, e não uma esperança de que o agente abra sozinho o documento certo. Um benefício extra: um script da camada 3 pode simplesmente ser executado pelo agente, sem que o código inteiro entre no contexto.

Skills, CLAUDE.md e comandos com barra: as diferenças

Os três mecanismos transmitem instruções ao agente, mas em momentos diferentes e com custos diferentes para o contexto.

A regra prática para escolher é simples. Se a instrução é necessária em quase toda tarefa, ela pertence ao CLAUDE.md. Se é necessária em tarefas de um tipo específico, é um skill. Se você mesmo digita sempre o mesmo pedido longo, é candidato a comando ou a skill acionado manualmente.

Não transfira proibições rígidas para o skill. O skill pode nem ser carregado, e a regra «nunca commitar segredos» precisa valer sempre. Esses invariantes permanecem no CLAUDE.md e, sempre que possível, são reforçados por mecanismos: hooks, permissões de acesso, verificações no CI.

Como criar um skill para o Claude Code: passo a passo

1. Encontre um procedimento recorrente. Bom sinal: você já explicou três vezes a mesma coisa ao agente, ou o CLAUDE.md tem uma seção de que só uma tarefa em dez precisa.
2. Crie a pasta .claude/skills/<nome>/ e o arquivo SKILL.md dentro dela.
3. Escreva o frontmatter com name e description, deixando claro quando aplicar o skill.
4. Descreva os passos com comandos concretos e critérios de conclusão: o que verificar e qual resultado conta como sucesso.
5. Tire o trecho longo para arquivos vizinhos e faça referência a eles no texto principal.
6. Remova a duplicação do CLAUDE.md, deixando uma linha de apontamento: «Deploy — skill deploy».
7. Teste: em uma sessão nova, peça a tarefa com suas próprias palavras, sem citar o nome do skill, e veja se o agente o acionou. Se não acionou, reescreva a descrição.

Exemplos de skills

Skill de deploy

O candidato clássico: o procedimento é raro, longo e perigoso, e um erro custa caro. No skill ficam registrados a ordem dos passos (primeiro a execução de teste, depois o envio), o que não pode ser publicado, como conferir o resultado e como reverter. O agente não precisa manter isso na cabeça a cada alteração de código — só quando o assunto é o servidor.

Skill de revisão

---
name: review
description: Revisão das alterações atuais antes do commit. Usar quando pedirem para revisar o diff, encontrar erros nas alterações ou preparar as mudanças para o commit.
---

# Revisão de alterações

1. Obter o diff: `git diff` e `git diff --staged`.
2. Para cada arquivo alterado, verificar:
   - a entrada do usuário é escapada na saída;
   - as consultas SQL são parametrizadas;
   - não há saída de depuração nem arquivos temporários.
3. Rodar os testes e o linter do projeto (os comandos estão no CLAUDE.md).
4. Relatório: lista de problemas com arquivo e linha, dos mais graves aos menores.
   Se não houver problemas, dizer isso, sem inventar observações.

Esse skill transforma «veja se está tudo bem» em uma verificação reproduzível, com o mesmo conjunto de itens a cada vez.

Skill de encerramento de sessão

Outro tipo útil é um ritual no fim do trabalho: parar o ambiente local, apagar arquivos temporários, registrar no diário de progresso o que foi feito e o que falta, e fazer um commit com descrição detalhada. Isso resolve diretamente a perda de contexto entre sessões: a sessão seguinte começa com o estado atual do repositório, e não com suposições.

Erros típicos

• Descrição vaga. O skill existe, mas o agente não o aciona. A solução é reescrever a description com gatilhos concretos.
• Skill com cara de muro de texto. Foi transferida para o SKILL.md uma seção antiga de 400 linhas. O problema de contexto inchado voltou, só que mais tarde. Mantenha o texto principal curto e os detalhes em arquivos vizinhos.
• Duplicação com o CLAUDE.md. O mesmo procedimento está descrito em dois lugares e, com o tempo, os textos divergem. A fonte da verdade deve ser uma só.
• Skills que se sobrepõem. Dois skills com descrições parecidas — o agente escolhe entre eles ao acaso. Separe-os com «use / não use» explícitos.
• Comandos desatualizados. O script foi renomeado, mas o skill ainda aponta para o nome antigo. O skill faz parte do código do projeto: altere-o no mesmo commit que o procedimento.

Como saber que chegou a hora de tirar uma seção para um skill

Vale revisar periodicamente o CLAUDE.md e perguntar, para cada seção: em que parcela das tarefas comuns ela realmente é necessária? Se é necessária quase sempre, ela está no lugar certo. Se é necessária em uma tarefa de cada dez, é candidata a skill.

O segundo sinal é o tamanho. Uma seção que não cabe em uma tela quase sempre descreve um procedimento, e não uma regra. Procedimentos são mais fáceis de ler por inteiro na hora de executar, em vez de ficar sempre ocupando espaço no fundo da sessão.

O terceiro sinal são as explicações repetidas. Se você volta a dar ao agente os mesmos esclarecimentos sobre a mesma tarefa, registre-os uma vez no skill. Depois de uma semana, veja se diminuiu o número de correções manuais: essa é a prova de que o skill funciona.

Resumo

Skills do Claude Code são uma forma de guardar procedimentos junto ao projeto sem pagar por eles com contexto em cada sessão. A descrição do skill fica sempre visível, o corpo é carregado quando necessário, e os arquivos auxiliares, mais tarde ainda. No CLAUDE.md permanecem o mapa do projeto e as regras rígidas; para os skills vão deploy, revisão, releases e outras tarefas de um tipo específico. A organização dos arquivos de instrução e a divulgação progressiva do contexto são tratadas na prática no curso de harness engineering.