Como escrever uma Skill do Claude Code: SKILL.md, frontmatter e descrições que realmente disparam

As skills do Claude Code resolvem um problema que todo usuário intensivo acaba encontrando: você fica colando a mesma checklist, o mesmo procedimento ou as mesmas regras da casa no chat, ou uma seção do seu CLAUDE.md cresceu em silêncio até virar um manual que o modelo lê pela metade a cada requisição. Uma skill empacota essas instruções em um arquivo que o agente carrega sob demanda: você pode invocá-la com um slash command, ou o Claude pode carregá-la sozinho quando decide que ela é relevante.

Este guia cobre como escrever uma Skill do Claude Code do zero: o formato exato do SKILL.md, os campos de frontmatter que importam, por que o campo description decide se a sua skill algum dia dispara, e os erros que transformam skills em peso morto. Toda afirmação mecânica abaixo vem da documentação oficial do Claude Code da Anthropic; a orientação de qualidade vem do que aprendemos construindo o gerador gratuito de skills do Claude Code do PromptArch e nosso linter de arquivos de contexto.

O que é uma skill e quando usar uma

Uma skill é um diretório contendo um arquivo SKILL.md. O arquivo tem duas partes: frontmatter YAML entre marcadores --- que diz ao Claude quando usar a skill, e um corpo em markdown com as instruções que o Claude segue quando a skill roda. O nome do diretório vira o comando que você digita (.claude/skills/migration-review/SKILL.md gera /migration-review), e a descrição ajuda o Claude a decidir quando carregá-la por conta própria.

A decisão entre uma skill e outras superfícies de configuração se resume ao comportamento de carga:

• CLAUDE.md fica sempre ativo. Cada linha ocupa contexto em toda requisição, seja relevante ou não. Ele deve conter fatos duráveis: arquitetura, convenções, comandos, restrições. Se quiser um ponto de partida, o PromptArch tem um gerador de CLAUDE.md gratuito.
• Uma skill é sob demanda. Só a descrição curta fica sempre em contexto; o corpo carrega quando a skill é invocada. A regra prática da própria Anthropic: crie uma skill quando você fica colando as mesmas instruções no chat, ou quando uma seção do CLAUDE.md cresceu até virar um procedimento em vez de um fato. Material de referência longo dentro de uma skill não custa quase nada até você precisar dele.
• Slash commands agora são skills. Os comandos personalizados foram fundidos ao sistema de skills: um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam ambos /deploy e funcionam do mesmo jeito. Skills são a forma recomendada porque adicionam um diretório para arquivos de apoio, frontmatter para controlar quem as invoca e carregamento automático disparado pelo modelo.

Onde você guarda a skill decide o escopo dela: ~/.claude/skills/<name>/SKILL.md é pessoal (todos os seus projetos), .claude/skills/<name>/SKILL.md é de projeto (commitada no repo, compartilhada com o time), e plugins podem empacotar skills sob o próprio namespace.

Anatomia: um SKILL.md completo

Aqui está uma skill de projeto realista que revisa novas migrações de banco de dados. Salve em .claude/skills/migration-review/SKILL.md:

---
name: migration-review
description: Reviews a SQL migration for destructive operations, lock risk,
  and rollback safety. Use when the user adds or edits a migration file,
  asks to review a migration, or mentions ALTER TABLE, DROP COLUMN,
  backfills, or "is this migration safe".
allowed-tools: Read Grep
---

# Migration review

Review the migration $ARGUMENTS against this checklist:

1. Flag destructive operations (DROP TABLE, DROP COLUMN, TRUNCATE) and
   confirm a backup or archival step exists before them.
2. Check long-running statements: adding a NOT NULL column with a default
   on a large table, or an index built without CONCURRENTLY, locks writes.
3. Verify new foreign keys have a supporting index on the referencing side.
4. Confirm the migration is reversible, or that the PR notes why it is not.
5. Check RLS: any new table needs policies before it ships, because our
   API reads it through the anon client.

Report findings as a short list ordered by severity. If everything passes,
say so in one line.

As peças:

• Frontmatter. Todos os campos são opcionais; só description é recomendado, porque é o que o Claude lê para decidir quando aplicar a skill. name é apenas o rótulo exibido nas listagens (o nome do comando vem do diretório). allowed-tools pré-aprova ferramentas durante o turno que invoca a skill, para o Claude não parar para pedir permissão.
• Corpo. Instruções em markdown puro. $ARGUMENTS é substituído pelo que vem depois do nome da skill quando você digita /migration-review supabase/migrations/039_foo.sql; se o placeholder não existir, o Claude Code anexa o seu texto ao final.
• Extras úteis. disable-model-invocation: true torna a skill apenas manual (certo para fluxos tipo /deploy com efeitos colaterais). user-invocable: false a esconde do menu /, para conhecimento de fundo que não é uma ação com sentido. context: fork roda a skill em um subagente isolado. E uma linha com ! seguida de um comando de shell entre backticks roda antes de o Claude ver o conteúdo, injetando saída ao vivo (um diff, uma lista de arquivos) no prompt.

A descrição é o campo decisivo

Este é o modelo mental que separa as skills que disparam das que apodrecem: a descrição é um roteador, e o Claude é o motor de roteamento. Em uma sessão normal, o Claude vê uma listagem com o nome e a descrição de cada skill. Quando a sua requisição chega, ele compara as suas palavras com essas descrições e decide qual skill carregar, se alguma. O corpo da sua skill, por melhor que seja, é invisível na hora do roteamento.

Isso tem três consequências práticas:

1. Diga o que a skill faz E quando usá-la. "Revisa migrações SQL" é metade de uma descrição. A metade de disparo ("usar quando o usuário adiciona um arquivo de migração, pede para revisar uma migração ou menciona ALTER TABLE...") é o que de fato é comparado.
2. Cubra as frases que as pessoas realmente digitam. Inclua o vocabulário da requisição, não o vocabulário da solução. Usuários dizem "essa migração é segura?", não "realize uma análise de risco de locks". Se a descrição não contém as palavras deles, a skill nunca ativa, e você vai concluir errado que skills não funcionam.
3. Coloque o caso de uso principal primeiro. O texto combinado de description mais when_to_use é truncado em 1.536 caracteres na listagem de skills, e com muitas skills instaladas a própria listagem tem um orçamento de contexto, então adiante a frase que importa. O campo opcional when_to_use existe exatamente para orientação de ativação estendida: requisições de exemplo e formulações que deveriam ativar a skill.

Uma ressalva: definir disable-model-invocation: true remove a descrição do contexto por completo. Esse é o objetivo (o Claude não pode dispará-la), mas significa que todo esse conselho de roteamento vale só para skills que o Claude tem permissão de invocar.

Divulgação progressiva: mantenha o corpo enxuto

Skills são baratas até serem carregadas. As descrições ficam sempre em contexto; o corpo completo entra na conversa só quando a skill é invocada. Mas, uma vez invocado, o corpo renderizado permanece em contexto pelo resto da sessão, então cada linha é um custo recorrente de tokens. Daí seguem duas regras:

• Diga o que fazer, não por quê. Aplique o mesmo teste de concisão que você aplicaria ao CLAUDE.md. A dica da Anthropic: mantenha o SKILL.md abaixo de 500 linhas.
• Empurre o volume para arquivos de apoio. O diretório de uma skill pode conter reference.md, examples.md, templates ou scripts executáveis ao lado do SKILL.md. Referencie-os a partir do corpo ("para os detalhes completos da API, ver reference.md") e o Claude os lê apenas quando necessário. Essa é a segunda camada de divulgação progressiva: descrição sempre, corpo ao invocar, arquivos de apoio sob demanda.

O que pertence a uma skill, e o que não

Bom material para skill: fluxos de vários passos (release, deploy, triagem), checklists de revisão, procedimentos específicos do repo ("como escrevemos migrações", "como montamos um changelog") e material de referência profundo atrás de um SKILL.md fino. Em resumo: procedimentos e playbooks.

Mau material para skill: fatos duráveis sobre o codebase (isso é CLAUDE.md), coisas que você quer impor de forma determinística a cada edição (isso são hooks), política de permissões (isso é settings) e prompts de uso único que você nunca vai reutilizar. O erro de posicionamento mais comum é a duplicação: as mesmas regras vivendo no CLAUDE.md e em uma skill ao mesmo tempo. Elas se dessincronizam com o tempo, e você paga pela cópia do CLAUDE.md em absolutamente toda requisição.

Erros comuns

• Descrições vagas que nunca disparam. "Ajuda com coisas de banco de dados" não roteia nada. É a razão número um de skills ficarem sem uso.
• Skills que duplicam o CLAUDE.md. Se é um fato que o agente precisa o tempo todo, vai no CLAUDE.md uma vez só. Se é um procedimento, tire-o do CLAUDE.md por completo e mova para a skill.
• Corpos gigantes. Um SKILL.md de 900 linhas derrota a divulgação progressiva; depois de uma invocação, vira um imposto permanente sobre a sessão.
• Efeitos colaterais autoativáveis. Se uma skill faz deploy, commita ou manda mensagem para pessoas, adicione disable-model-invocation: true. Você quer digitar /deploy deliberadamente, não deixar o Claude decidir que o seu código parece pronto.
• Antipadrões dentro do corpo. Corpos de skill são instruções para um agente, então as mesmas regras respaldadas por pesquisa que valem para o CLAUDE.md valem aqui: inflação de ênfase (muralhas de MUST/NEVER/CRITICAL), frases evasivas tipo "try to... if possible" que soam opcionais, e proibições sem razão nem alternativa degradam de forma mensurável os modelos atuais. Nosso linter as marca (antipattern/emphasis-inflation, antipattern/weak-language, antipattern/bare-prohibition e cerca de 30 outras); cole o corpo da sua skill em lint para uma checagem gratuita e offline, e veja a lista completa de regras com as fontes.

Teste o disparo, depois a saída

Ver uma skill disparar diz que o Claude a encontrou, não que ela fez o que você pretendia, então meça as duas coisas separadamente:

1. Confiabilidade do disparo. Em uma sessão nova (o contexto residual de quando você a escreveu mascara as lacunas), digite algumas requisições realistas que deveriam ativar a skill e algumas que não. Se ela subativa, adicione as frases que faltam à descrição ou ao when_to_use. Se superativa, torne a descrição mais específica ou deixe-a apenas manual.
2. Invocação direta como controle. /skill-name sempre funciona para skills invocáveis pelo usuário, e perguntar "What skills are available?" confirma que a skill está registrada. Se /skill-name funciona mas o frontmatter parece ignorado, o suspeito de sempre é YAML malformado: o Claude Code então carrega o corpo com metadados vazios, e claude --debug mostra o erro de parse.
3. Qualidade da saída. Rode os mesmos prompts com a skill disponível e com ela desabilitada, e compare. O plugin skill-creator da Anthropic automatiza esse ciclo com casos de teste guardados, execuções isoladas, avaliação de passa/falha e ajuste da descrição.

Itere primeiro sobre a descrição. Ela é a linha de maior alavancagem do arquivo inteiro.

Gere uma em dois minutos

Você pode escrever um SKILL.md à mão com tudo o que está acima. Ou pode deixar que a estrutura, o frontmatter, a descrição orientada a disparo e um corpo limpo para o linter sejam gerados para você: o gerador gratuito de skills do Claude Code do PromptArch guia você por nome, descrição, gatilhos, permissões de ferramentas e passos do fluxo, e produz um SKILL.md pronto para salvar. A primeira é grátis, sem cadastro. Depois passe-a pelo lint e suba para o .claude/skills/ do seu repo.