Skill do Claude Code com exemplos ou com regras: o que o modelo segue melhor?

Fala aí, beleza? Tu abre o editor pra criar o SKILL.md, escreve o frontmatter e trava exatamente na primeira linha do corpo: eu listo as regras ou eu mostro exemplos de entrada e saída?

Parece papo de estilo, mas essa escolha mexe direto no quanto o Claude acerta quando a tarefa aparece de um jeito que tu não previu

E a melhor parte: a própria documentação de autoria de skills tem posição sobre isso, com preferência declarada pra um lado e um conceito bem útil pra decidir o outro

Bora destrinchar? 🙂

Como uma skill é lida pelo Claude (e por que isso muda a escrita):

Antes de decidir regra ou exemplo, vale entender o que o modelo enxerga e QUANDO ele enxerga

Uma Skill é uma pasta com um arquivo SKILL.md na raiz. Dentro dele tem um frontmatter YAML entre marcadores ---, com name e description, e o corpo em markdown com as instruções

.claude/skills/revisando-pull-request/
└── SKILL.md

---
name: Revisando pull request
description: Revisa o diff de um pull request procurando bug e regressão. Use quando o pedido for revisar mudanças de código antes do merge.
---

# Revisando pull request

Instruções em markdown aqui

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

As propriedades permitidas no frontmatter são allowed-tools, compatibility, description, license, metadata e name

Skill pessoal mora em ~/.claude/skills/<nome-da-skill>/ e skill de projeto mora em .claude/skills/<nome-da-skill>/

Em plugin, as skills ficam num diretório skills/ na raiz do plugin (my-plugin/skills/<nome>/SKILL.md) e o comando sai namespaced, no formato /meu-plugin:nome

Detalhe que pega muita gente: em skill pessoal ou de projeto, o comando de invocação vem do NOME DA PASTA. O campo name é só o rótulo que aparece na listagem (em skill de plugin, o name define o último segmento do comando e o prefixo do plugin continua lá)

E o que é divulgação progressiva?

Essa é a parte que muda a redação inteira

Na inicialização do agente, só o name e a description de cada skill entram no system prompt. O corpo do SKILL.md (e os arquivos extras) só é lido depois, quando o Claude julga que aquela skill ajuda na tarefa, usando as ferramentas de leitura de arquivo

Ou seja: tem duas camadas de escrita, com trabalhos diferentes

A description é a camada de ACIONAMENTO. Ela precisa dizer o quê + quando, e a recomendação é nome em forma gerúndia (verbo + ndo)

O corpo é a camada de EXECUÇÃO. E aqui entra o princípio que a documentação bate na tecla: seja conciso, porque a janela de contexto é um bem público compartilhado

Guarda isso, porque é justamente o que faz regra e exemplo custarem coisas diferentes…

Skill com regras versus skill com exemplos: comparação direta

Os dois estilos não competem pelo mesmo trabalho, e é aí que mora a confusão

A orientação de autoria de skills prefere ENUNCIAR A REGRA E EXPLICAR O PORQUÊ, em vez de diretiva rígida em caixa alta do tipo MUST, ALWAYS ou NEVER. O motivo é bem pragmático: explicar o porquê permite ao Claude generalizar pra casos que a skill não previu

Do outro lado, a mesma documentação afirma que exemplos transmitem o estilo e o nível de detalhe desejados com mais clareza do que descrições sozinhas, e ilustra isso com pares de entrada e saída pra formato de mensagem de commit

A tabela abaixo separa quem faz o quê:

Repara que a coluna do meio ganha em GENERALIZAÇÃO e a da direita ganha em REPRODUTIBILIDADE

E tem mais um detalhe da orientação de few-shot que quase ninguém segue: os exemplos precisam ser relevantes, diversos e cobrir casos de borda. Cinco exemplos parecidos entre si ensinam quase a mesma coisa que um só

Em tarefa de classificação, a regra é ainda mais dura: incluir exemplos de TODAS as classes

Em que tipo de tarefa cada estilo funciona melhor

A documentação dá um conceito que resolve essa escolha muito melhor que gosto pessoal: graus de liberdade (degrees of freedom)

A ideia é casar o nível de liberdade com o tipo de tarefa, e não escrever toda skill do mesmo jeito

Alta liberdade: instruções em texto, use seu julgamento

É o caso de tarefa aberta, tipo code review

Não tem uma saída única certa. O que existe é critério: o que importa olhar, o que é grave, o que é ruído

Aqui a regra explicada domina. Tu escreve o que quer e por quê, e o modelo aplica isso em código que tu nunca viu

Exemplo demais nesse cenário faz o Claude imitar o formato do exemplo em vez de pensar no diff que chegou

Média liberdade: pseudocódigo e scripts parametrizados

É o fluxo que tu prefere, mas que aceita variação

Aqui os dois convivem bem: a regra dá o caminho, e um exemplo ou dois mostram como fica na prática quando o cenário é o comum

Baixa liberdade: script exato, sem flags, não modifique este comando

É a operação frágil, tipo migração de banco

Nesse caso o exemplo deixa de ser ilustração e vira TEMPLATE A COPIAR. Se existe um único jeito certo de rodar, mostrar o jeito certo é mais seguro que descrever o jeito certo

E o formato de saída?

A orientação é fornecer templates de formato de saída, casando o nível de rigidez com a necessidade

Requisito estrito (resposta de API, formato de dados)? Template exato, e o exemplo entrega isso melhor que qualquer descrição

Adaptação é útil? Formato padrão adaptável, com a regra explicando quando adaptar

É o mesmo raciocínio que aparece quando o assunto é regras de breakpoint que o modelo segue: quanto mais fixo o resultado esperado, mais o exemplo carrega o peso

Como descobrir qual estilo funciona na sua skill

Agora a parte que separa achismo de resposta: medir na TUA skill 🙂

A documentação recomenda um fluxo orientado a avaliação, e ele existe justamente porque a resposta muda de skill pra skill

1. Monte os cenários de avaliação ANTES de escrever documentação extensa. Pega as lacunas reais, os casos em que o Claude erra hoje, e transforma cada um num cenário de teste. O erro comum deste passo: escrever o SKILL.md completão primeiro e só depois pensar em como medir se ele ajudou
2. Meça a linha de base sem a skill. Roda os mesmos cenários com o Claude puro e anota o resultado. O erro comum deste passo: comparar duas versões da skill sem nunca ter medido o baseline, aí tu não sabe se a skill melhorou algo ou se o modelo já acertava sozinho
3. Escreva instruções mínimas. Versão curta, sem enfeite, no estilo que tu acha que resolve. O erro comum deste passo: já nascer com 300 linhas de corpo, porque aí não dá pra saber qual pedaço fez efeito
4. Rode as avaliações e compare contra o baseline. É esse delta que responde a pergunta do post na TUA skill, não a opinião de ninguém
5. Faça o A/B às cegas entre as duas versões. A Anthropic mantém o repositório público anthropics/skills com Agent Skills open source, incluindo a skill-creator, que ganhou recursos de teste e medição: avaliações, benchmarks (taxa de acerto, tempo e uso de tokens) e comparator agents que fazem comparação A/B entre duas versões de skill, ou skill versus ausência de skill, julgando as saídas SEM saber qual é qual
6. Ajuste a description pra reduzir falso positivo e falso negativo de acionamento. Skill que não dispara não tem estilo bom nem ruim, ela simplesmente não roda. Vale a mesma investigação de quando a skill não funciona no projeto. O erro comum deste passo: mexer no name achando que ele é o comando, quando em skill pessoal ou de projeto o comando vem do nome da pasta e o name é só o rótulo exibido na listagem
7. Itere com duas instâncias. Uma instância do Claude ajuda a projetar e refinar a skill, a outra usa a skill em tarefas reais. Ciclo de observar, refinar, testar, e repete
8. Teste com todos os modelos que você pretende usar. O que um modelo pega pela regra, outro pode precisar ver exemplificado

Veredito: qual estilo o modelo segue melhor

Vou ser honesto no fechamento, do jeito que a evidência disponível permite

Os EXEMPLOS ganham quando o que tu quer é formato reproduzível e a saída tem forma fixa. Mensagem de commit, resposta de API, formato de dados: mostrar o par de entrada e saída comunica o nível de detalhe de um jeito que descrição nenhuma alcança

A REGRA COM JUSTIFICATIVA ganha quando a skill vai encontrar caso fora do previsto. É literalmente o argumento da documentação: explicar o motivo permite ao Claude generalizar pro que a skill não cobriu, coisa que a diretiva seca em caixa alta não faz

A combinação vencedora, então, é bem menos dramática que a pergunta do título: regra explicada + poucos exemplos bem escolhidos, dentro do grau de liberdade certo da tarefa, sem inflar o contexto

E aqui vai o aviso importante: esse veredito é a posição da documentação de autoria de skills, não resultado de teste feito por mim. Eu não tenho número de aderência comparando os dois estilos, e não vou inventar um pra fechar o post bonitinho

Quem decide de verdade é o A/B na TUA base de avaliações 😉

Conclusão

No fim, três princípios centrais de autoria seguram tudo que a gente viu: ser conciso (a janela de contexto é um bem público compartilhado), definir o grau de liberdade adequado à tarefa e testar com todos os modelos que você pretende usar

Regra explica o critério e sobrevive ao caso não previsto

Exemplo trava o formato e o nível de detalhe

O próximo passo é bem concreto e cabe hoje: escreve a versão mínima da tua skill, cria dois ou três cenários de avaliação, mede o baseline sem a skill e roda a comparação entre a versão com regras e a versão com exemplos

Só depois disso vale a pena crescer o SKILL.md

até o próximo post!