5 regras de escrita do body SKILL.md escondidas na doc da Anthropic

Um Skill precisa de apenas duas linhas de YAML frontmatter para existir. Mas a forma como você escreve o body determina completamente a qualidade do resultado.

Depois de cruzar a documentação oficial da Anthropic e o blog de engenharia, destilei os mecanismos de funcionamento e os princípios de escrita do body em cinco regras. Tudo começou porque meus próprios Skills falhavam intermitentemente no carregamento, e aproveitei um feriado prolongado para verificar tudo do zero.

Se você não entende a ordem de execução dos Skills, o design do body vai falhar

Skills não são injetados na conversa como um prompt. Na inicialização, apenas o name e a description são carregados no prompt do sistema.

Quando a solicitação do usuário coincide com a description, o Claude usa a ferramenta Bash para ler o SKILL.md completo. Só então carrega arquivos de referência e scripts conforme necessário. O blog de engenharia da Anthropic chama essa estrutura de “divulgação progressiva (progressive disclosure)”.

• Fase 1: Apenas metadados (name + description) ficam sempre carregados. Cerca de 100 tokens por Skill.
• Fase 2: O body do SKILL.md entra na janela de contexto apenas quando há correspondência.
• Fase 3: Arquivos das pastas scripts e references são carregados no momento de uso real.
• Quando scripts são executados, o código em si não entra no contexto, apenas a saída é consumida.

Sem entender essa estrutura, você vai encher o body de informação desnecessária e pular o que realmente importa.

Escrever “quando usar” no body desperdiça tokens

Muita gente adiciona uma seção “When to Use This Skill” no body. Depois de criar meus próprios Skills, descobri que isso é completamente inútil. O body só é lido depois que o Skill já foi ativado.

“Quando usar” pertence exclusivamente à description. O repo oficial skill-creator da Anthropic deixa isso explícito.

• A description é o único mecanismo de ativação (o Claude não consulta conteúdo de “quando usar” no body)
• Descriptions têm limite de 1.024 caracteres. Escrever em terceira pessoa melhora a precisão de descoberta.
• O body deve conter regras da tarefa, procedimentos e formatos de saída esperados.
• Delete frases como “Use este Skill quando…” do body.

Mantenha o body abaixo de 500 linhas e separe o resto

A primeira linha do guia da Anthropic afirma que a janela de contexto é um recurso compartilhado. Uma vez carregado, um Skill divide tokens com o histórico de conversa e o prompt do sistema.

A recomendação oficial é manter o body abaixo de 500 linhas e extrair conteúdo detalhado para arquivos separados. O SKILL.md funciona como sumário, e os arquivos de referência servem como capítulos individuais.

• Body abaixo de 500 linhas recomendado (indicado nas best practices da Anthropic)
• Arquivos de referência devem ser linkados a apenas um nível de profundidade a partir do SKILL.md
• Com dois ou mais níveis de referências aninhadas, o Claude pode ler apenas as primeiras 100 linhas via head -100
• Adicione um sumário no início de qualquer arquivo de referência com mais de 100 linhas

Escreva partindo do princípio de que o Claude já é inteligente

Explicar o que é um PDF no body desperdiça tokens. Existe um princípio que o guia da Anthropic enfatiza repetidamente:

“Não escreva o que o Claude já sabe.”

Um exemplo de código conciso de 50 tokens supera uma explicação conceitual de 150 tokens. Nos meus testes com a mesma tarefa de extração de PDF, o body conciso produziu uma precisão visivelmente melhor que o verboso.

• Para cada frase, pergunte-se: “Esta explicação vale os tokens gastos?”
• Substitua explicações conceituais por exemplos de código + formatos de saída esperados
• Classifique a liberdade da tarefa em três níveis (alta/média/baixa) para calibrar a intensidade das instruções
• Defina liberdade baixa para tarefas como migrações de banco de dados. Alta para revisões de código.

Incorpore loops de verificação no body para melhorar a qualidade

Executar → verificar → corrigir → re-verificar. Este é o padrão de body mais prático recomendado pela Anthropic. Incorporar checklists no body reduz visivelmente as chances do Claude pular etapas.

O guia oficial também observa que linguagem forte como “MUST filter” alcança maior taxa de conformidade que “always filter”.

• Detalhe os passos em formato de checklist para tarefas complexas
• Inclua loops de verificação de script → correção de erro → re-verificação no body
• Use “MUST” em vez de “always”, a taxa de conformidade do Claude melhora
• Escreva mensagens de erro específicas para que o Claude possa se autocorrigir

O essencial

A description decide quando um Skill dispara. O body decide como ele executa. No momento em que você mistura esses dois papéis, o Skill não dispara corretamente e a qualidade da saída cai.

Um bom Skill é como um bom documento de onboarding. Os documentos mais poderosos partem do princípio de que o leitor já é inteligente.