Uma skill é um índice, não um manual. Ela ensina o agente a fazer do seu jeito, sempre igual.

Descrição + corpo

A descrição (em terceira pessoa: "cria faturas e envia lembretes") é o que o agente lê para decidir se usa a skill. O corpo traz as regras mais importantes no topo, os passos e os links para o resto. Curto: só o que o modelo não deduz sozinho.

Detalhe sob demanda

Preços, termos, formatos, exemplos de entrada e saída, um arquivo por assunto, todos linkados direto do SKILL.md. Arquivo longo começa com um sumário, para que mesmo uma leitura parcial mostre tudo o que ele cobre.

O que não pode variar

Onde um erro custa dinheiro, apaga dados ou publica algo, o passo vira script exato. Onde a regra tem de valer em toda execução, ela sai do texto e vira hook, que o Claude Code roda sozinho, siga ou não a skill.

SKILL.md curto, um nível de profundidade

Corpo abaixo de 500 linhas; o resto em arquivos linkados direto do SKILL.md. Arquivo que só se alcança por outro arquivo pode ser apenas pré-visualizado (as primeiras linhas), e as regras lá embaixo somem.

Sumário no topo de arquivo longo

Referência com mais de 100 linhas começa com uma lista do que contém. Assim, mesmo lendo só o início, o agente sabe que "descontos" está no fim e vai até lá.

Grau de liberdade pelo risco

Alto: instrução simples (brainstorm). Médio: modelo com variação (relatório semanal). Baixo: script exato (fatura, imposto, migração). Uma skill mistura os três; o teste é "e se o agente fizer este passo diferente?".

Teste em cada modelo que vai usar

Haiku: a skill orienta o bastante? Sonnet: é clara e econômica? Opus e Fable: evita explicar demais? Faça o teste nas skills de que você depende; o restante não compensa o custo.

Só o que o modelo não sabe

O contexto é um bem público. Não explique o que é uma fatura; guarde os seus preços, termos e regras internas. Descrição em terceira pessoa, com as palavras que a pessoa digita.

Checklist com linha de "voltar"

Tarefa de muitos passos ganha uma lista que o agente copia na resposta e vai marcando, cada passo com "pronto quando…" e uma linha do tipo "se o total não bater, volte ao passo 2".

Loop de verificação

Rodar, corrigir o que falhou, repetir até passar. A checagem não precisa ser código: comparar o rascunho com o guia de estilo e listar cada desvio vale igual. Para trabalho longo, um verificador com contexto limpo bate a autocrítica.

Padrões para saída definida

Template dizendo quão rígido é; dois ou três pares de entrada e saída quando o estilo importa; fluxo condicional quando há bifurcação. Um padrão e uma saída de emergência, nunca um cardápio de cinco opções.

Feita para compartilhar

Não assuma que a biblioteca está instalada na máquina do colega: liste os pacotes exatos com a linha de instalação ao lado do script que precisa deles. A Claude API não instala nada.

Regra que não pode quebrar vira hook

"Nunca enviar fatura acima de R$ 50 mil sem aprovação" em caixa alta é seguido quase sempre. Hook é seguido sempre: declarado no frontmatter da skill, roda antes de cada comando e fica ativo o resto da sessão.

Teste antes de apagar

Passo a passo do que o modelo já sabe, listas longas de comportamento e bom senso repetido costumam ser peso morto. Só uma execução com e outra sem a linha prova isso.

Peça a resposta

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.

Regra com porquê

"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 e diz ao próximo editor quando a regra deixou de importar.

Caixa alta só para linha dura

"Comece pelo resultado, depois o detalhe" funciona tão bem quanto listar cada comportamento indesejado. Quando tudo grita, nada se destaca.

Diga como e quando se confere

Para execução longa ou de risco, um subagente que não fez o trabalho confere contra a especificação. É o mesmo método da área Execução Longa.

Uma pasta em ~/.claude/skills

git clone https://github.com/inematds/auditar-skills && cp -r auditar-skills/skill-creator-plus ~/.claude/skills/

No Codex, a mesma pasta em ~/.agents/skills. No claude.ai, zipe SKILL.md, references/ e scripts/.

Todas as skills de uma vez

python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills

Uma tabela por skill: erros, avisos e as regras violadas (FM, DS, ST, CT, WF, SC, NM, HK, TS, LB). --json para processar.

AUDIT · NEW · REFINE

"Audite a minha skill de deploy" gera o relatório, fail primeiro, com arquivo e linha. "Transforme isso numa skill" escreve três prompts de teste antes da pasta. "A skill esquece o filtro de data, conserte" reescreve a regra em torno do motivo, geralmente mais curta.

skill-creator (Claude Code)

Vem com o Claude Code: cria, mede e otimiza a descrição de uma skill, com avaliações e comparação de variantes. É o ponto de partida; o /skill-doctor aponta skills sem uso.

writing-skills (Superpowers)

A skill do kit Superpowers para escrever e testar skills com TDD de documentação: baseline sem skill, cenário de pressão, depois a skill. Coberta no curso Superpowers do INEMA.

Skills For Real Engineers (Matt Pocock)

Os nomes dos modos de falha (no-op, duplicação, sedimento, dispersão, conclusão precoce) vêm daqui. Curso do INEMA abaixo.