SKILL.md é o arquivo que explica para o Claude Code o que uma Skill faz, quando ela deve ser usada e qual processo seguir.
Na prática, ele funciona como a ficha operacional da Skill: no topo ficam os metadados, principalmente a description; no corpo ficam as instruções em Markdown.
Resposta rápida
Um bom SKILL.md tem:
namecurto;descriptionespecífica;- objetivo da Skill;
- quando usar;
- quando não usar;
- processo passo a passo;
- critérios de qualidade;
- formato de saída;
- exemplos;
- indicação de arquivos de apoio, se existirem.
Exemplo mínimo:
<pre><code>— name: briefing-conteudo description: Use quando o usuário pedir um briefing de conteúdo para artigo SEO, GEO ou blog.
Briefing de conteúdo
Crie um briefing com:
- Intenção de busca.
- Público-alvo.
- Estrutura H2/H3.
- Perguntas frequentes.
- Links internos sugeridos.
- Fontes necessárias.</code></pre>
Esse arquivo já é suficiente para uma Skill simples. Se a rotina crescer, você pode adicionar arquivos em references/, scripts/ ou outras pastas de apoio.
O que é SKILL.md?
SKILL.md é o arquivo principal de uma Claude Skill.
Segundo a documentação do Claude Code, Skills estendem o que Claude consegue fazer: você cria um arquivo SKILL.md com instruções, e Claude adiciona essa Skill ao conjunto de capacidades disponíveis.
O ponto importante é que Skill não é só um prompt salvo. Uma Skill deve ensinar um processo reutilizável.
Use SKILL.md quando você tem uma rotina que volta sempre:
- revisar artigo antes de publicar;
- montar briefing de SEO;
- auditar campanha;
- validar tracking;
- criar relatório para cliente;
- revisar Pull Request;
- gerar documentação;
- preparar plano de conteúdo.
Se a tarefa é rara, pequena ou ainda confusa, comece com um prompt normal. Depois, quando o processo ficar claro, transforme em Skill.
Estrutura recomendada de SKILL.md
Uma estrutura simples e forte é:
<pre><code>— name: nome-da-skill description: Use quando…
Nome da Skill
Objetivo
Quando usar
Quando não usar
Processo
Critérios de qualidade
Formato de saída
Exemplos</code></pre>
Você não precisa usar todos os blocos sempre. Mas essa ordem evita três problemas comuns:
- Skill genérica demais;
- instrução solta sem processo;
- saída final imprevisível.
Para uma Skill pequena, Objetivo, Processo e Formato de saída já costumam resolver.
Como funciona o frontmatter
O frontmatter fica no topo do SKILL.md, entre três traços.
Exemplo:
<pre><code>— name: qa-publicacao description: Use quando o usuário pedir validação final de artigo, página ou landing page antes ou depois de publicar. —</code></pre>
O name identifica a Skill. O description ajuda Claude a entender quando deve usar aquela Skill.
Em Claude Code, a Skill pode ser usada automaticamente quando a tarefa combina com a descrição, ou chamada diretamente pelo nome, como /qa-publicacao.
Por que a description pesa tanto?
A description é importante porque Claude não deve carregar todas as instruções completas de todas as Skills o tempo todo.
O fluxo ideal é sob demanda:
- Claude vê que a Skill existe.
- A descrição indica quando ela deve ser usada.
- Quando a tarefa combina, Claude carrega o conteúdo necessário.
- Se houver referências ou scripts, eles entram quando fizerem sentido.
Isso deixa o contexto mais limpo, mas cria uma responsabilidade: a descrição precisa ser específica.
Uma descrição como “ajuda com marketing” é fraca porque pode significar briefing, copy, relatório, criativo, SEO ou campanha. Uma descrição como “Use quando o usuário pedir relatório mensal de marketing para cliente com métricas e próximos passos” é muito mais acionável.
Como escrever uma boa description
A description não é slogan. Ela é gatilho.
Compare:
| Description fraca | Description melhor |
|---|---|
| Ajuda com marketing | Use quando o usuário pedir análise de campanha de Meta Ads |
| Faz SEO | Use quando o usuário pedir revisão SEO, GEO ou editorial de artigo antes de publicar |
| Relatórios | Use quando o usuário pedir relatório mensal de marketing para cliente com métricas e próximos passos |
| Conteúdo | Use quando o usuário pedir briefing de artigo para blog com intenção de busca, estrutura e fontes |
Uma boa descrição responde:
- qual tarefa a Skill resolve;
- em qual contexto ela deve aparecer;
- quando não deve ser usada, se houver risco de confusão;
- qual tipo de entrega ela ajuda a produzir.
Exemplo mais restrito:
<pre><code>description: Use quando o usuário pedir revisão SEO, GEO ou editorial de artigo antes de publicar. Não use para escrever artigo do zero.</code></pre>
Esse final reduz acionamento errado. Para Skills de trabalho real, esse tipo de limite vale ouro.
O que colocar no corpo do SKILL.md
O corpo do arquivo deve ser operacional.
Prefira instruções que Claude consiga executar:
- listas numeradas;
- critérios objetivos;
- sequência de decisão;
- comandos literais;
- nomes de arquivos;
- formato final esperado;
- exemplos curtos.
Evite:
- teoria longa;
- frases motivacionais;
- regras contraditórias;
- contexto que muda toda semana;
- instruções vagas como "faça o melhor possível";
- credenciais, chaves de API ou dados sensíveis.
Pense no SKILL.md como um manual de execução, não como um artigo.
Exemplo de SKILL.md para agência de marketing
Aqui vai um exemplo mais completo:
<pre><code>— name: relatorio-cliente-marketing description: Use quando o usuário pedir um relatório de marketing para cliente com resumo executivo, métricas e próximos passos.
Relatório de marketing para cliente
Objetivo
Transformar dados de campanha, SEO ou conteúdo em um relatório claro para cliente.
Quando usar
Use quando houver dados de performance, período analisado e necessidade de explicar resultado para cliente.
Quando não usar
Não use para criar campanha do zero. Não use quando faltarem métricas básicas como período, canal e objetivo.
Processo
- Identifique período analisado.
- Separe métricas de resultado e métricas de diagnóstico.
- Explique o que melhorou.
- Explique o que piorou.
- Aponte hipóteses, não certezas falsas.
- Liste decisões recomendadas.
Formato de saída
Entregue:
- resumo executivo;
- números principais;
- leitura dos resultados;
- próximos passos;
- riscos.</code></pre>
Esse exemplo é bom porque tem escopo, limite e formato de entrega. Claude não precisa adivinhar o que fazer.
Quando usar references, scripts e arquivos de apoio
Um SKILL.md não precisa carregar tudo.
Se o arquivo passou de muitas páginas, talvez ele esteja tentando resolver tarefas demais ou guardar material que deveria ficar separado.
Estrutura possível:
<pre><code>relatorio-cliente-marketing/ SKILL.md references/ modelo-relatorio.md glossario-metricas.md exemplos-boas-leituras.md scripts/ validar-planilha.py</code></pre>
Use references/ para conhecimento de apoio:
- modelos;
- checklists longos;
- glossários;
- exemplos;
- padrões editoriais.
Use scripts/ quando a tarefa precisa de precisão:
- validar JSON;
- contar palavras;
- extrair dados;
- checar links;
- transformar arquivos;
- gerar tabelas;
- rodar QA repetível.
O SKILL.md deve dizer quando abrir cada arquivo.
Exemplo:
<pre><code>Antes de gerar o relatório, leia references/modelo-relatorio.md. Use references/glossario-metricas.md apenas se houver métricas pagas. Rode scripts/validar-planilha.py quando o usuário anexar CSV ou XLSX.</code></pre>
Isso mantém a Skill leve e evita gastar contexto com coisa desnecessária.
SKILL.md e CLAUDE.md são a mesma coisa?
Não.
CLAUDE.md costuma guardar memória e convenções gerais do projeto: comandos, arquitetura, padrões, decisões e contexto recorrente.
SKILL.md guarda um processo reutilizável.
Uma regra simples:
| Use CLAUDE.md para | Use SKILL.md para |
|---|---|
| Convenções do projeto | Rotinas repetíveis |
| Comandos de build/teste | Checklists e processos |
| Contexto permanente | Capacidades acionáveis |
| Padrões gerais | Tarefas específicas |
Se uma parte do CLAUDE.md virou um procedimento grande que você repete sempre, ela provavelmente merece virar Skill.
Checklist para revisar um SKILL.md
Antes de considerar pronto, confira:
- o nome é curto?
- a descrição diz quando usar?
- a descrição evita acionamento errado?
- existe processo claro?
- a saída esperada está definida?
- os limites estão explícitos?
- os exemplos ajudam sem poluir?
- não há credenciais?
- não há dado perecível desnecessário?
- arquivos de apoio estão bem separados?
- dá para testar com um pedido real?
Depois teste com três pedidos:
| Teste | Exemplo | Resultado esperado |
|---|---|---|
| Deve acionar | "Revise esse artigo antes de publicar" | Usa a Skill |
| Não deve acionar | "Escreva um artigo do zero" | Não usa a Skill de revisão |
| Ambíguo | "Dá uma olhada nesse texto" | Pergunta ou usa com cuidado |
Se a Skill aciona demais, restrinja a description.
Se aciona de menos, deixe a description mais direta.
Perguntas frequentes
O que é SKILL.md no Claude Code?
SKILL.md é o arquivo principal de uma Claude Skill. Ele contém metadados e instruções que Claude usa para entender quando aplicar aquela Skill e qual processo seguir.
O que colocar no description do SKILL.md?
Coloque uma frase clara dizendo quando Claude deve usar a Skill, para qual tarefa e em qual contexto. Se necessário, inclua também quando não usar.
SKILL.md pode ter código?
O arquivo SKILL.md é Markdown, mas a pasta da Skill pode incluir scripts, referências e arquivos de apoio para tarefas mais precisas.
SKILL.md é igual CLAUDE.md?
Não. CLAUDE.md guarda contexto e convenções gerais do projeto. SKILL.md guarda um processo reutilizável para uma tarefa específica.
Uma Skill precisa ser grande?
Não. Muitas Skills boas são pequenas, focadas e fáceis de testar. Se o arquivo ficar grande demais, separe referências e scripts.
Posso chamar uma Skill manualmente?
Sim. No Claude Code, além do uso automático quando a tarefa é relevante, você pode chamar uma Skill diretamente pelo nome, como /nome-da-skill.