Anatomia de um SKILL.md
Em resumo
- O cabeçalho define nome e descrição; a descrição é o gatilho.
- O corpo tem instruções; arquivos de apoio ficam em pastas separadas.
O que vai em cada parte do arquivo de uma Skill e por que a ordem importa.
O cabeçalho define nome e descrição; a descrição é o gatilho.
Guia completo e atualizadoAbri o arquivo de uma Skill que não estava funcionando e o problema estava na primeira linha: a descrição dizia "análise de mídia" e eu pedia "por que o ROAS caiu". A IA nunca conectou as duas coisas. Troquei a descrição, e a Skill passou a disparar. Desde então, gasto mais tempo no cabeçalho do que no corpo, e este artigo explica por quê.
Vou percorrer cada parte de um SKILL.md: o que vai onde, o que decide se a Skill é ativada, o que a torna legível para o modelo e onde as pessoas erram.
O cabeçalho: nome e descrição
O arquivo começa com um bloco de metadados. O nome identifica a Skill; a descrição diz o que ela faz e quando deve ser usada. Essa descrição é lida antes de qualquer coisa e é o único critério para carregar a Skill ou não. Se o pedido do usuário não combina com ela, o corpo nunca é lido.
Uma boa descrição tem três partes: o que a Skill faz, os gatilhos (frases que a pessoa diria) e, quando importa, quando não usar. "Analisa campanhas de Google Ads e decide cortar, corrigir ou escalar. Use ao pedir análise de Google Ads, por que o ROAS caiu, negativar termos. Não use para Meta."
Skills, prompts salvos e GPTs personalizados
Três formas de reutilizar instruções e quando cada uma faz sentido. →
O corpo: instruções que cabem em uma leitura
Depois do cabeçalho vem o procedimento. A regra prática: deve caber em uma leitura de segundos. Ordem, verbos no imperativo, um passo por linha. Se um passo precisa de explicação longa, ele vira uma frase no corpo e um arquivo de referência com o detalhe.
O corpo também diz o formato de saída e o que evitar. Esses dois blocos curtos previnem a maioria das respostas genéricas.
Referências: o detalhe mora fora
Tabelas de padrão, glossários, exemplos longos, regras de nomenclatura, scripts. Ficam em arquivos na mesma pasta e são citados no corpo: "para o padrão de nomes, leia referencias/nomenclatura.md". A IA abre só quando precisa, o que economiza contexto e mantém o corpo limpo.
Erro comum: colar tudo no arquivo principal. O modelo lê 400 linhas, se perde e passa a ignorar o começo.
Scripts
Quando a tarefa exige código repetitivo (consolidar planilhas, chamar uma API), o script fica na pasta da Skill e o corpo diz quando rodar. Assim a IA não reescreve o script a cada uso, e você revisa uma vez.
Exemplos: bom e ruim, com motivo
Um exemplo de resultado aprovado e um de resultado reprovado, cada um com uma linha explicando o porquê. Podem ficar no corpo se forem curtos, ou em referência se forem longos. Sem exemplo, o modelo acerta o conteúdo e erra a forma.
O que decide se a Skill dispara
Só a descrição. Nem o nome, nem o corpo. Por isso ela precisa conter as palavras que você usa. Um teste que faço: escrevo cinco pedidos diferentes para a mesma tarefa, do jeito que eu falaria, e confiro se a descrição cobre todos. Quando dois pedidos usam palavras que não estão lá, acrescento.
Erros de estrutura que mais vejo
Descrição que descreve o tema em vez da tarefa ("marketing digital" em vez de "escreve o resumo semanal de campanhas"). Passos escritos como prosa longa, sem ordem clara. Formato de saída ausente, o que gera uma tabela numa semana e uma lista na outra. Exemplo colado sem dizer por que é bom. Referência mencionada mas não citada no passo em que é usada, então a IA não a abre.
Cada um desses tem um sintoma reconhecível: Skill que não dispara, passo pulado, formato inconsistente, resposta correta com forma errada, detalhe ignorado. Quando o sintoma aparece, o erro de estrutura correspondente é o primeiro lugar para olhar.
Um modelo mínimo
Cabeçalho com nome e descrição com gatilhos. Corpo com: quando usar, passos numerados, formato de saída, o que evitar, exemplo bom e ruim, referências citadas. Cinco a trinta linhas. Tudo além disso é referência. Se você olhar o seu arquivo e ele tiver mais que isso no corpo, provavelmente dá para mover algo para fora.
Na minha rotina
Todas as minhas Skills seguem o mesmo esqueleto, e isso me permite abrir qualquer uma e entender em segundos o que ela faz. Quando uma para de funcionar, olho primeiro a descrição, depois o formato de saída, depois os exemplos, nessa ordem, porque é a ordem de frequência dos erros. As referências mais usadas são o padrão de nomenclatura e a tabela de metas, compartilhadas entre várias Skills, o que significa que corrijo em um lugar só.
Perguntas frequentes
Qual o tamanho ideal do corpo?
Poucas telas, legível em segundos. O detalhe vai para referências.
Posso ter uma Skill sem referências?
Sim, e a maioria começa assim. Referências aparecem quando o corpo cresce.
A IA lê as referências sempre?
Só quando o corpo manda. Por isso cite cada uma no passo em que é usada.
Posso escrever em português?
Sim. Escreva no idioma em que você faz os pedidos, para os gatilhos baterem.
Fontes e método
- Documentação de Skills da Anthropic
- Estrutura padronizada das Skills próprias, 2025 e 2026
Continue sua pesquisa
Próximos passos selecionados para esta jornada.
Skills, prompts salvos e GPTs personalizados
Três formas de reutilizar instruções e quando cada uma faz sentido.
Entender →Arquitetura de um app com LLM
As peças de um sistema que usa modelo de linguagem e como elas se encaixam.
Ver como fazer →Perplexity: busca com IA e fontes
Ferramenta de pesquisa que responde com citações e links.
Comparar →