# 5 regras de escrita do body SKILL.md escondidas na doc da Anthropic > Author: Tony Lee > Published: 2026-02-17 > URL: https://tonylee.im/pt/blog/anthropic-skill-md-body-writing-rules/ > Reading time: 5 minutes > Language: pt > Tags: ai, claude-code, developer-tools, skills, productivity ## Canonical https://tonylee.im/pt/blog/anthropic-skill-md-body-writing-rules/ ## Rollout Alternates en: https://tonylee.im/en/blog/anthropic-skill-md-body-writing-rules/ ko: https://tonylee.im/ko/blog/anthropic-skill-md-body-writing-rules/ ja: https://tonylee.im/ja/blog/anthropic-skill-md-body-writing-rules/ zh-CN: https://tonylee.im/zh-CN/blog/anthropic-skill-md-body-writing-rules/ zh-TW: https://tonylee.im/zh-TW/blog/anthropic-skill-md-body-writing-rules/ ## Description Cinco princípios de escrita do body SKILL.md enterrados na documentação oficial da Anthropic. Da separação de papéis entre description e body aos loops de verificação. ## Summary 5 regras de escrita do body SKILL.md escondidas na doc da Anthropic is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - Se você não entende a ordem de execução dos Skills, o design do body vai falhar - Escrever "quando usar" no body desperdiça tokens - Mantenha o body abaixo de 500 linhas e separe o resto - Escreva partindo do princípio de que o Claude já é inteligente - Incorpore loops de verificação no body para melhorar a qualidade - O essencial ## Content 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. ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/pt/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/pt/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/pt/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/pt/blog/anthropic-skill-md-body-writing-rules/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/pt/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.