📚 De onde vêm as regras
Os números desta aula foram conferidos em outubro de 2026 no guia oficial Skill authoring best practices e nos docs de skills, hooks e janela de contexto do Claude Code. As regras de base estão estáveis há cerca de um ano; o que mudou foram os modelos. Os ajustes para os modelos 5.5, no fim, vêm de outra fonte e estão marcados como tal.
Conteúdo detalhado
📏 Tamanho e profundidade
O SKILL.md é um sumário, não um manual. O guia oficial pede o corpo
abaixo de 500 linhas; o resto vai para arquivos de referência linkados
direto do SKILL.md. Referência que só se alcança passando por outra referência é
aninhada: o agente pode ler apenas a pré-visualização dela (as primeiras linhas, algo como um head -100)
e as regras do fim do arquivo somem sem aviso.
linhas é o teto do corpo do SKILL.md. Passou disso, divida por assunto em references/.
de profundidade: cada referência é linkada pelo próprio SKILL.md, nunca só por outra referência.
linhas ou mais numa referência pedem um sumário no topo, para que até uma leitura parcial mostre tudo o que o arquivo cobre.
# Pricing reference
## Contents
- Base prices per plan
- Regional taxes
- Discounts and coupons <- at the end, but listed here
- Refund rules
## Base prices per plan
...💡 Dica prática
Abra o SKILL.md e conte quantas referências ele cita. Toda referência que aparece só dentro de outra referência é candidata a subir um nível, com uma linha "leia X quando Y" no SKILL.md.
🎚️ Graus de liberdade
Nem todo passo merece o mesmo controle. O guia classifica em graus de liberdade: quanto mais frágil e caro o erro, menos espaço o agente deve ter. Uma mesma skill costuma misturar os três. O teste para cada passo é simples: "e se o agente fizer este passo de um jeito diferente?"
Instrução em texto
Várias respostas servem e o contexto decide. Ex.: brainstorm de títulos, revisão de código pelo bom senso.
Modelo com espaço para variar
Existe um padrão preferido, mas dá para adaptar. Ex.: relatório semanal com template e parâmetros.
Script exato, sem parâmetros soltos
Erro custa dinheiro, apaga dados ou publica algo. Ex.: fatura, imposto, migração de banco: "rode exatamente este script".
💡 Dica prática
A imagem do guia: uma ponte estreita com abismo dos dois lados pede corrimão (grau baixo); um campo aberto pede só a direção (grau alto). Marque cada passo da sua skill com A, M ou B antes de reescrever.
🏷️ Descrição: terceira pessoa, "quando usar" e limites
A descrição entra no prompt de sistema junto com a de todas as outras skills. Por isso o guia pede terceira pessoa ("Processa planilhas…", nunca "Eu posso…" ou "Você pode…"), o que a skill faz e quando usar, com as palavras que a pessoa digita. E há limites de tamanho:
caracteres é o máximo do campo description no frontmatter.
caracteres é onde o Claude Code corta description + when_to_use somados na listagem de skills. O que passar disso o modelo não vê.
✓ Terceira pessoa + quando
"Generates invoices and sends payment reminders. Use when the user asks to bill a client, issue an invoice or chase a late payment."
✗ Primeira pessoa, sem gatilho
"I can help you with invoices."
💡 Dica prática
Vale o mesmo para o corpo: só o que o modelo não sabe. Não explique o que é uma fatura; guarde os seus preços, termos e regras internas. O contexto é dividido com a conversa, as outras skills e o histórico.
✅ Checklist na resposta e loop de verificação
Tarefa de muitos passos ganha uma checklist que o agente copia na resposta e vai marcando, com uma linha de volta: "se o total não bater, volte ao passo 2". E toda saída que importa passa por um loop rodar → corrigir → repetir até a checagem passar. A checagem não precisa ser código: comparar o rascunho com o guia de estilo e listar cada desvio também conta.
Copy this checklist into your answer and tick each step:
- [ ] 1. Read the client data
- [ ] 2. Compute totals with scripts/total.py
- [ ] 3. Validate: python3 scripts/check_invoice.py out.json
- [ ] 4. Generate the PDF
If step 3 fails, fix the data and go back to step 2.
Only continue when validation passes.⚠️ Atenção
"Revise bem antes de entregar" não é loop. Loop tem um critério que passa ou falha e uma instrução do que fazer quando falha. Para trabalho longo, um verificador com contexto limpo, que não fez o trabalho, costuma achar mais que a autocrítica.
🧪 Teste em cada modelo
A mesma skill se comporta diferente em cada modelo. O guia oficial pede para testar em todos os modelos que vão usá-la e cita três perguntas, uma por família: Haiku, Sonnet e Opus. A página não menciona o Fable.
A skill orienta o bastante? Modelo menor precisa de mais detalhe.
Está clara e econômica?
Evita explicar demais? Modelo grande sofre com instrução redundante.
💡 Dica prática
Teste nas skills de que você depende, com três pedidos reais cada. Nas outras, o custo do teste não compensa.
📦 Pacotes, hooks e compactação
Três regras práticas para a skill sobreviver fora da sua máquina e numa sessão longa:
Pacotes com a linha de instalação
Não assuma que a biblioteca está instalada na máquina do colega: liste os pacotes exatos com o comando de instalação ao lado do script que precisa deles. Na Claude API a skill não instala nada; só o que já está no ambiente.
Regra que não pode quebrar vira hook
Caixa alta é seguida quase sempre; hook é seguido sempre. No Claude Code, o hook pode ser declarado no frontmatter da própria skill: depois que ela é carregada, ele roda antes de cada comando e fica ativo pelo resto da sessão.
Compactação guarda só o começo
Quando a conversa é compactada, o Claude Code mantém só os primeiros 5.000 tokens de cada skill carregada. Regra crítica no fim de um SKILL.md longo pode sumir depois da compactação: as mais importantes vão no topo.
---
name: invoices
description: Generates invoices and sends payment reminders. Use when
the user asks to bill a client, issue an invoice or chase a late
payment. Not for accounting reports.
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/check-limit.sh"
---
# Invoices
Critical rules first: never send an invoice above the approval
limit without a human OK. (the hook enforces it)🆕 Ajustes para os modelos 5.5
Segundo o guia de prompting do Claude Fable 5 e do Opus 5.5 citado pelo skill-creator-plus (RoboNuggets, MIT), skills escritas para modelos antigos tendem a ser prescritivas demais e podem piorar o resultado. Não é texto da página de boas práticas de skills; trate como orientação de prática e confirme no seu uso.
Passo a passo do que o modelo já sabe e bom senso repetido costumam ser peso morto. Só uma execução com e outra sem a linha prova isso.
Instrução para "escrever o raciocínio passo a passo" pode ser recusada pelos modelos 5.5. Peça a resposta, uma explicação curta ou o resumo das ações.
"Abaixo de 1.536 caracteres, porque o Claude Code corta aí" deixa o modelo tratar o caso que a regra não previu.
Quando tudo grita, nada se destaca. Uma frase de direção vale uma lista de proibições.
📋 Checklist copiável
Cole numa conversa com o agente junto com a sua skill, ou use você mesmo antes de publicar.
Confira esta skill contra as regras abaixo e marque cada item: - [ ] O corpo do SKILL.md tem menos de 500 linhas - [ ] Cada referência é linkada direto do SKILL.md, sem referência aninhada - [ ] Toda referência com mais de 100 linhas começa com um sumário - [ ] Cada passo tem o grau de liberdade certo: texto, modelo ou script exato - [ ] A descrição está em terceira pessoa e diz o que faz e quando usar - [ ] A descrição tem no máximo 1.024 caracteres e, somada ao when_to_use, cabe em 1.536 - [ ] O corpo traz só o que o modelo não sabe - [ ] Tarefa longa tem checklist que o agente copia na resposta, com linha de volta - [ ] Existe um loop rodar, corrigir e repetir com critério que passa ou falha - [ ] A skill foi testada em cada modelo que vai usá-la - [ ] Todo pacote usado tem a linha de instalação ao lado - [ ] Regra que não pode quebrar virou hook no frontmatter da skill - [ ] As regras críticas estão no topo, dentro dos primeiros 5.000 tokens - [ ] Nenhuma instrução pede para escrever o raciocínio na resposta Para cada item que falhar, diga onde está o problema e proponha a correção antes de editar.
🔎 Audite as suas skills com o validador
A parte mecânica dessas regras dá para medir. O auditar-skills (projeto INEMA, espelho do robonuggets/skill-creator-plus, licença MIT) traz um validador em Python puro, sem instalar nada e sem chamar API, que lê a pasta de skills e lista erros e avisos por regra. Guia: inematds.github.io/auditar-skills/guia.
git clone https://github.com/inematds/auditar-skills cp -r auditar-skills/skill-creator-plus ~/.claude/skills/ python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills
📊 Exemplo real
Numa máquina de produção do INEMA, com a pasta ~/.claude/skills cheia de skills próprias e de terceiros, o validador rodou em cerca de um segundo:
- ST5 · sumário ausente em referência com mais de 100 linhas: o maior ofensor, 268 ocorrências.
- DS3 · descrição sem "quando usar": 75 skills.
- ST4 · referência aninhada: 60 ocorrências.
💡 Dica prática
Meça antes de reescrever. Comece pelas skills que você mais usa e pelos erros mais baratos de corrigir: sumário no topo e "quando usar" na descrição resolvem a maior parte da lista.
✏️ Exercícios práticos
1. Rode o validador
Rode o comando acima na sua pasta de skills e anote as três regras que mais aparecem. Compare com o exemplo real desta aula.
2. Marque os graus de liberdade
Escolha uma skill sua com mais de cinco passos e marque cada passo como alto, médio ou baixo. Algum passo de grau baixo está escrito como instrução solta? Troque por script.
3. Passe a checklist numa skill real ⭐
Cole a checklist copiável e a sua skill numa conversa com o Claude. Corrija os itens que falharem, rode o validador de novo e confirme que o número de erros caiu.
🎯 Resumo do módulo
Fim da Trilha 1:
Você já entende a anatomia, a estrutura, o gatilho e as regras atuais. Na Trilha 2 você dissecará uma skill real do começo ao fim e construirá a sua.