🧭 O que mudou (e o que não mudou)
Circulam vídeos sobre "10 regras novas" para skills. Conferindo na página oficial de boas práticas da Anthropic e nos docs do Claude Code, as regras de base estão estáveis há cerca de um ano. O que mudou foram os modelos: Fable 5, Opus 5.5 e Sonnet 5.5 seguem instruções mais à risca e fazem mais sozinhos. Uma skill escrita para modelos antigos continua funcionando, mas pode carregar peso morto.
O aviso que motivou esta aula
Segundo o guia de prompting citado pelo skill-creator-plus, skills escritas para modelos antigos costumam ser prescritivas demais para os modelos 5.5 e podem piorar o resultado. Não localizamos essa frase na documentação oficial; trate-a como hipótese a testar na sua skill, não como regra da Anthropic.
Estável (já visto no curso)
- ›SKILL.md abaixo de 500 linhas
- ›Divulgação progressiva em três níveis
- ›Descrição como gatilho: o que faz e quando usar
O que esta aula acrescenta
- ›Graus de liberdade por passo
- ›Limites de caracteres e o corte de 5.000 tokens
- ›Hooks na skill, sem pedir raciocínio, checklist com retorno
🎚️ Graus de liberdade: alto, médio, baixo
A doc oficial pede para ajustar o quanto você especifica cada passo ao quanto ele é frágil. A imagem da Anthropic: numa ponte estreita com penhasco dos dois lados, corrimão exato; num campo aberto, uma direção e confiança. O teste para cada passo é uma pergunta: "e se o agente fizer este passo de outro jeito?"
Alto
Instrução em texto simples. Várias abordagens servem e o contexto decide.
Ex.: revisão de código, brainstorm.
Médio
Modelo ou script com parâmetros. Há um padrão preferido e alguma variação é aceitável.
Ex.: relatório semanal.
Baixo
Script exato, com poucos ou nenhum parâmetro. Erro custa caro ou a ordem não pode mudar.
Ex.: fatura, imposto, migração de banco.
uma skill, três graus:
## 1. Draft the post (high) Write in the brand voice. Context decides the angle. ## 2. Build the summary (medium) Use templates/summary.md. Sections may grow or shrink. ## 3. Publish (low) Run exactly: python scripts/publish.py --verify Do not add flags.
💡 Dica
Uma skill boa costuma misturar os três: escrita livre, resumo com modelo, publicação travada num comando. Travar tudo deixa a skill rígida; soltar tudo deixa o passo arriscado ao acaso.
✍️ Descrição em terceira pessoa, com "quando usar"
A descrição é a única parte da skill que o agente vê antes de escolhê-la, entre possivelmente mais de cem. Ela entra no prompt de sistema, por isso a doc pede terceira pessoa ("Cria faturas…", não "Eu crio…" nem "Você pode…"). Formato: uma frase sobre o que a skill faz, depois "Use quando…" com as situações e as palavras que a pessoa realmente digita. E só o que o modelo não sabe: não explique o que é uma fatura.
✗ Não dispara bem
- ✗"Eu ajudo com faturas." (primeira pessoa, sem quando)
- ✗"Você pode usar para documentos." (vago)
- ✗Gatilho principal no fim de um texto longo
✓ Dispara
- ✓"Cria faturas a partir da planilha de horas e envia lembretes de cobrança. Use quando a pessoa pedir fatura, cobrança ou lembrete de pagamento."
- ✓Caso de uso principal primeiro
Máximo do campo description, sem tags XML (best-practices da Anthropic).
O Claude Code corta description + when_to_use somados nesse ponto da listagem de skills. O que passa disso o agente não lê.
💡 Dica
Quando a listagem passa do orçamento, o Claude Code também descarta descrições inteiras de skills pouco usadas. Mais um motivo para pôr o gatilho mais importante na primeira frase.
🪝 Hooks no frontmatter da skill
Texto é seguido com julgamento: pode ser pulado e, depois da compactação, só o começo da skill fica. "Nunca enviar fatura acima de R$ 50 mil sem aprovação" em caixa alta é seguido quase sempre. Hook é seguido sempre. A novidade é que a própria skill pode declarar seus hooks no frontmatter: eles registram quando a skill é chamada e ficam ativos o resto da sessão.
SKILL.md (Claude Code):
---
name: safe-deploying
description: Deploys the app to staging with a safety check on
each shell command. Use when the user asks to deploy or ship.
disable-model-invocation: true
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/check-command.sh"
---
A skill é chamada
Os hooks do frontmatter entram em vigor nesse momento.
O evento acontece
Antes de cada comando Bash, o Claude Code roda o script, siga o agente a skill ou não.
Até o fim da sessão
O hook continua registrado. Use once: true no hook que só deve rodar na primeira vez que der certo.
💡 Dica
Julgamento fica no texto; linha dura vira hook. Hooks são só do Claude Code: no claude.ai, mantenha a regra em texto e perto do topo.
🗜️ Compactação: só os primeiros 5.000 tokens ficam
Quando a conversa é compactada, o Claude Code reanexa só os primeiros 5.000 tokens de cada skill em uso. Uma regra importante lá no fim de um SKILL.md longo simplesmente some numa sessão comprida. Por isso a ordem do arquivo é ordem de importância.
✗ Ordem que perde regra
- ✗História do projeto e contexto geral no topo
- ✗"Regras importantes" como última seção
✓ Ordem que sobrevive
- ✓Regras que não podem falhar logo no início
- ✓Instruções permanentes ("confira a saída depois de cada mudança"), não passos de uma vez só
- ✓Detalhe em references/, linkado direto do SKILL.md
🚫 Não peça o raciocínio na resposta
Instruções do tipo "escreva o seu raciocínio passo a passo" ou "transcreva o que você pensou" podem ser recusadas pelos modelos 5.5 (a recusa reasoning_extraction). A skill para no meio sem fazer o trabalho. Peça o resultado: a resposta, uma explicação curta dela ou o resumo das ações.
✗ Troque
- ✗"Mostre todo o seu raciocínio antes da resposta."
- ✗"Pense passo a passo e escreva cada pensamento."
✓ Por
- ✓"Comece pelo resultado e explique em duas frases por que ele vale."
- ✓"No fim, liste as ações que você executou."
Os outros ajustes para modelos novos
- ★Corte o andaime, mas teste antes: passo a passo do que o modelo já sabe e bom senso repetido são candidatos a sair. Só uma execução com e outra sem a linha prova que era peso morto.
- ★Dê o motivo: "abaixo de 1.536 caracteres, porque o Claude Code corta a listagem aí" deixa o modelo tratar o caso que a regra não previu.
- ★Direcione em uma frase: caixa alta só para linha dura. Quando tudo grita, nada se destaca.
- ★Verificação explícita: diga como e quando o trabalho é conferido; em execução longa, um subagente que não fez o trabalho confere contra a especificação.
☑️ Checklist copiada + "volte ao passo X"
Para tarefa de muitos passos, a doc recomenda dar ao agente uma checklist que ele copia na própria resposta e vai marcando. Cada passo termina num "pronto quando…" que dá para conferir, e a lista diz para onde voltar quando uma checagem falha. Assim o agente não pula etapa nem declara vitória cedo.
no SKILL.md:
Copy this checklist into your reply and tick each step: - [ ] 1. Load the timesheet done when: every row has hours - [ ] 2. Compute the totals done when: sum matches the sheet - [ ] 3. Render the invoice done when: PDF opens, 1 page - [ ] 4. Validate python scripts/validate.py out.pdf If step 4 fails on the total, go back to step 2.
💡 Dica
A checagem não precisa ser código: comparar o rascunho com o guia de estilo e listar cada desvio também é um loop de verificação. Rodar, corrigir o que falhou, repetir até passar.
🔎 Audite antes de reescrever
Não reescreva skills de memória: meça. O projeto INEMA auditar-skills é o espelho do skill-creator-plus (RoboNuggets, licença MIT), com guia em português. O validador é Python puro, sem instalar nada e sem chamar API: checa a parte mecânica de todas as skills de uma pasta em cerca de um segundo.
dentro da pasta do auditar-skills:
python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skillsskills auditadas numa máquina real (a do Nei)
erros encontrados
skills sem nenhum erro
Os maiores ofensores
- ST5Referência com mais de 100 linhas sem sumário no topo. Uma leitura parcial não mostra tudo o que o arquivo cobre.
- ST4Referência aninhada: arquivo que só se alcança por outro arquivo pode ser apenas pré-visualizado (as primeiras linhas). Tudo linkado direto do SKILL.md.
- DS3Descrição sem "quando usar", sem as palavras que a pessoa digita.
Rode o validador
Uma tabela por skill com erros, avisos e as regras violadas.
Escolha cinco
As com mais erros ou as que você mais usa. Auditar a biblioteca inteira não compensa o custo.
Relatório antes da edição
Peça o relatório e escolha o que aplicar. ST5 e ST4 são correções mecânicas.
Teste com e sem
Antes de apagar uma linha, rode a skill com e sem ela. Regra que precisa valer sempre vai para hook.
📋 Checklist das 10 regras (copie e use)
Antes de publicar ou ao revisar uma skill antiga, passe por esta lista. O botão copia em formato de checklist Markdown, pronta para colar no seu editor ou no pedido ao agente.
- SKILL.md abaixo de 500 linhas; todo arquivo de referência linkado direto do SKILL.md (um nível de profundidade).
- Referência com mais de 100 linhas começa com um sumário.
- Grau de liberdade pelo risco: texto livre onde o contexto decide, modelo onde há padrão, script exato onde o erro custa caro.
- Testada em cada modelo que vai usá-la (Haiku, Sonnet, Opus/Fable).
- Só o que o modelo não sabe; descrição em terceira pessoa, com "Use quando…" e as palavras que a pessoa digita.
- Descrição com até 1.024 caracteres; descrição + when_to_use abaixo de 1.536; caso de uso principal primeiro.
- Tarefa longa tem checklist que o agente copia na resposta, com "pronto quando…" e "se falhar, volte ao passo X".
- Loop de verificação: rodar, corrigir o que falhou, repetir até passar.
- Regras críticas no topo, porque após a compactação só os primeiros 5.000 tokens da skill ficam; nenhum pedido para escrever o raciocínio.
- Regra que não pode quebrar vira hook no frontmatter; pacotes listados com a linha de instalação.
💡 Fontes
Guia de boas práticas de skills da Anthropic (platform.claude.com), docs de skills, hooks e janela de contexto do Claude Code, conferidos em 6 de outubro de 2026. O aviso sobre skills prescritivas demais vem do guia de prompting citado pelo skill-creator-plus. Os números mudam: confira o link oficial antes de citar.
✅ Resumo do Módulo · Fim do Curso
Você concluiu o curso! 🎉
Cinco trilhas, da visão do ecossistema até governança e as regras de 2026. Agora é com você: rode o validador nas suas skills, corrija as cinco piores, escreva a próxima já dentro da checklist e continue aprendendo no portal.