Estruturando Instruções Passo a Passo Que Claude Pode Seguir Confiávelmente

A descrição faz com que uma Skill seja descoberta. As instruções decidem se ela realmente funciona.

Uma vez que Claude tenha correspondido uma tarefa a uma Skill, tudo a partir desse ponto depende do corpo do arquivo SKILL.md - os passos reais que ele deve seguir.

Instruções soltas, em estilo de parágrafo, tendem a produzir resultados inconsistentes: uma abordagem ligeiramente diferente a cada vez, detalhes tratados de forma diferente entre execuções, um final que varia em forma.

Esta página é sobre a estrutura que evita isso: passos claros e numerados que um leitor (e Claude) pode seguir da mesma maneira todas as vezes.

Resumo

• Ideia Central: Instruções estruturadas como passos ordenados e concretos produzem comportamento consistente; instruções escritas como prosa convidam à deriva.
• Por que Importa: Uma Skill que se comporta de maneira diferente a cada vez que é executada é difícil de confiar, mesmo que uma execução individual pareça razoável.
• Conceitos Chave: passos numerados, passos de ação única, verbos ambíguos, ramificação, final definido, granularidade dos passos.
• Quando Usar: Use isso sempre que estiver elaborando o corpo de uma Skill, ou quando uma Skill existente produzir resultados inconsistentes para tarefas semelhantes.
• Limitações / Compromissos: Passos altamente granulares melhoram a consistência, mas podem fazer tarefas simples parecerem excessivamente projetadas; a granularidade correta depende de quanto a tarefa realmente varia.
• Tópicos Relacionados: Escrevendo uma descrição eficaz, escopando o acesso a ferramentas, empacotando arquivos de referência, erros comuns de Skill.

Fundamentos

O corpo de instruções de um arquivo SKILL.md é o que Claude realmente executa assim que uma Skill é acionada. Seu trabalho é ser seguido da mesma maneira todas as vezes, não apenas ser lido uma vez e compreendido em espírito.

A forma mais confiável para isso é uma lista numerada de passos concretos.

## Instruções
 
1. Leia o diff do pull request fornecido pelo usuário.
2. Verifique cada arquivo alterado contra a lista de verificação da equipe (nomeação, testes, comentários).
3. Liste quaisquer itens da lista de verificação que falharem, com o arquivo e linha específicos.
4. Se todos os itens passarem, declare isso claramente em vez de listar as falhas.
5. Produza os resultados como um breve resumo de aprovação/reprovação por item da lista de verificação.

Cada linha numerada faz uma coisa. Não há um passo que diga "lidar apropriadamente com o código" - isso é um parágrafo fingindo ser um passo, e produzirá um resultado diferente dependendo do humor, fraseado e contexto a cada vez que for executado.

Compare isso com uma versão em parágrafo da mesma tarefa:

Analise o diff do PR e verifique-o contra nossa lista de verificação usual, anotando
qualquer coisa que não pareça correta, e informe ao usuário o que precisa ser corrigido
antes que possa ser mesclado.

Ambos descrevem a mesma tarefa subjacente. Apenas um deles diz a Claude, inequivocamente, o que verificar, em que ordem e qual deve ser a aparência da saída.

Mecânicas e Interações

A estrutura confiável de passos se resume a um pequeno número de hábitos, aplicados consistentemente.

Uma ação por passo. Se um passo contém "e" juntando duas ações genuinamente separadas, geralmente são dois passos. "Ler as notas e redigir um resumo" esconde um passo inteiro (decidir como agrupar as notas) dentro de uma única linha.

Verbos concretos sobre vagos. "Lidar com a formatação apropriadamente" e "revisar em busca de problemas" são frases comuns que soam como instruções, mas não especificam realmente uma ação. Substitua-as pela verificação real: "aplicar o guia de estilo da casa", "marcar qualquer função com mais de 40 linhas".

Ramificações explícitas em vez de condições enterradas. Quando uma tarefa realmente se divide com base na entrada, escreva a divisão como seu próprio passo com caminhos de sub-rotina rotulados, não como uma cláusula dentro de uma frase mais longa.

3. Verifique o comprimento da transcrição.
   3a. Se for inferior a 500 palavras, resuma em um único parágrafo.
   3b. Se for de 500 palavras ou mais, resuma com um parágrafo por tópico discutido.

Isso é mais verboso do que "resumir apropriadamente com base no comprimento", mas remove a adivinhação que faz com que execuções diferentes tracem a linha em lugares diferentes.

Um final definido. O último passo deve descrever exatamente o que é produzido - sua forma, não apenas "concluir". "Produza os quatro campos acima como um breve resumo estruturado" deixa muito menos espaço para deriva do que "forneça suas descobertas".

A granularidade dos passos deve corresponder à variabilidade real, não ao hábito. Uma tarefa com um caminho fixo único precisa de passos menos numerosos e mais amplos. Uma tarefa que genuinamente se ramifica com base na variação do mundo real precisa que essa variação seja explicitada. Adicionar passos numerados a uma tarefa que não tem pontos de decisão reais apenas adiciona ruído.

Muito amplo:  "1. Revise o documento e resuma-o."
Muito granular: "1. Abra o documento. 2. Leia a primeira frase.
              3. Leia a segunda frase. ..."
Granularidade correta: "1. Leia o documento completo. 2. Identifique as três principais
              afirmações. 3. Resuma cada afirmação em uma frase.
              4. Produza as três frases como uma lista numerada."

Considerações Avançadas e Aplicações

À medida que as instruções crescem além de um punhado de passos, duas escolhas estruturais adicionais começam a importar: agrupamento e referência.

Agrupar passos relacionados sob sub-títulos mantém um corpo de instruções longo escaneável, da mesma forma que um documento longo se beneficia de cabeçalhos de seção em vez de uma lista contínua.

## Instruções
 
### Coleta de Entrada
1. Leia as notas ou transcrição fornecidas.
2. Confirme se a entrada inclui um intervalo de datas; se estiver faltando, peça-o.
 
### Produção do Resumo
3. Agrupe os itens em enviados, em andamento e bloqueados.
4. Redija de três a cinco frases por grupo.
 
### Finalização
5. Produza o resumo agrupado como a resposta final.

Referenciar arquivos empacotados por nome, em vez de incorporar tudo, mantém a lista principal de passos focada na sequência de ações em vez do detalhe completo de qualquer uma delas. Um passo como "aplicar as regras de formatação em style-guide.md" aponta Claude para carregar esse arquivo apenas quando ele for realmente necessário, em vez de forçar cada execução a ler material de referência que a tarefa pode não exigir.

Um hábito útil depois que uma lista de passos é elaborada: leia-a como uma lista de verificação que um novo colega de equipe poderia seguir sem fazer uma pergunta de esclarecimento. Qualquer ponto onde você esperaria um "espere, o que isso significa?" é um passo que precisa ser mais concreto, dividido em uma ramificação ou reformulado com um verbo específico.

As instruções também se beneficiam do mesmo espírito de iteração que as descrições. Executar a Skill contra algumas entradas reais e variadas e comparar os resultados em busca de inconsistências indesejadas é a maneira mais confiável de encontrar passos que são realmente mais vagos do que pareciam no papel.

Concepções Equivocadas Comuns

• "Prosa bem escrita é tão confiável quanto passos numerados." - A prosa pode ser bem escrita e ainda deixar a sequência real de ações ambígua, já que a linguagem natural não força uma ordem explícita da maneira que uma lista numerada faz.
• "Mais passos sempre significam mais confiabilidade." - Preencher uma tarefa simples e linear com granularidade excessiva adiciona ruído sem adicionar consistência. A granularidade deve rastrear os pontos de decisão reais na tarefa.
• "Ramificações tornam as instruções muito complicadas para valer a pena escrever." - Uma ramificação não escrita não desaparece, apenas é resolvida de forma inconsistente no tempo de execução. Escrevê-la explicitamente é o que remove a inconsistência.
• "As instruções apenas precisam descrever o objetivo, não o processo." - Um objetivo claro sem um processo claro ainda deixa o caminho real para esse objetivo subespecificado, o que é exatamente o que produz deriva entre execuções.
• "Se a Skill funciona uma vez, as instruções estão boas." - Uma única execução bem-sucedida não testa a consistência. O teste real é se várias entradas diferentes, mas semelhantes, produzem resultados com a mesma forma.

FAQs

Relacionados

• Noções Básicas de Design e Empacotamento de Skills - um primeiro exemplo de trabalho de uma lista curta de passos.
• Escrevendo uma Descrição de Skill Eficaz Que Claude Acionará - o que deve ter sucesso antes que esses passos sejam realmente lidos.
• Tutorial: Empacotando Arquivos de Referência e Scripts em um Pacote de Skill - como referenciar detalhes de dentro de um passo.
• Escopando o Acesso a Ferramentas de uma Skill com allowed-tools - restringindo o que um passo tem permissão para fazer.
• Anatomia de um Arquivo SKILL.md - onde o corpo de instruções se encaixa no arquivo completo.

Versões da Stack: Escrito contra a linha de modelos Claude atual em aproximadamente Junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.