Exemplos na skill: por que mostrar o padrão funciona melhor do que descrever regras

A skill que ninguém segue costuma ser a que só descreve regras

Fala aí, beleza? Você escreveu a instrução, ela está lá no SKILL.md, bonitinha, talvez até em caixa alta pra dar ênfase, e mesmo assim o modelo faz diferente

Aí bate a dúvida clássica: será que ele leu?

Leu

Só que descrever um padrão em texto é uma coisa, e mostrar o padrão pronto é outra bem diferente

É a mesma lógica de quando você para de explicar o problema com suas palavras e simplesmente cola o erro: debugar a partir do log funciona melhor porque o material bruto carrega detalhe que a descrição perde no caminho

Neste post eu te mostro como trocar descrição abstrata por exemplo concreto de entrada e saída, como escolher exemplos que representam o padrão real do SEU trabalho, e como checar se aquilo mudou mesmo o comportamento

Bora ver na prática?

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O que você precisa antes de escrever os exemplos

Antes de sair colando exemplo, vale alinhar a base, porque metade dos problemas de skill mora na estrutura e não no conteúdo

Uma skill é um diretório que contém um arquivo SKILL.md, e esse arquivo é o único obrigatório

Scripts, documentos de referência e templates são opcionais, e ficam na mesma pasta

O SKILL.md abre com um frontmatter YAML entre marcadores ---, com os metadados obrigatórios name e description, e depois vem o conteúdo em Markdown com as instruções

Assim:

---
name: blog-stats
description: Levanta o desempenho dos posts do blog e monta o resumo da semana
---

## Instructions

...

## Examples

...

Guarda essa informação, porque ela volta lá no teste: no Claude Code, o frontmatter aceita também o campo disable-model-invocation, que desliga a ativação automática e deixa a skill só pra invocação manual

No Claude Code, skill pessoal mora em ~/.claude/skills/ e skill de projeto mora em .claude/skills/ dentro do repositório

E se liga nesse detalhe que pega muita gente: o nome da pasta é o identificador da skill

Ou seja, .claude/skills/blog-stats/ registra a skill como blog-stats, não importa o que você escreveu no título do Markdown lá dentro

.claude/skills/
└── blog-stats/
    └── SKILL.md

Se você ainda está decidindo se o caso pede uma skill mesmo ou uma integração via ferramenta externa, esse papo de quando usar skill ou MCP resolve boa parte da dúvida antes de você investir tempo escrevendo

E o mais importante pro assunto deste post: o template de SKILL.md da documentação oficial de boas práticas já vem com uma seção de Instructions E uma seção de Examples, com exemplos concretos de uso

A seção de exemplo não é enfeite, ela faz parte do formato desde o começo 🙂

Como escrever exemplos que mostram o padrão real do seu trabalho

Agora a parte que interessa

O checklist de qualidade da documentação oficial é bem direto num item: os exemplos precisam ser concretos, não abstratos

"Concreto" aqui não significa "mais detalhado", significa material real, do seu contexto, com nome de tabela, nome de campo, formato de saída, aquilo que você realmente usa no dia a dia

1. Defina de 2 a 3 casos de uso concretos antes de escrever qualquer coisa

A orientação oficial é identificar de 2 a 3 casos de uso concretos que a skill deve habilitar ANTES de escrever qualquer código

Escreve os três numa linha cada, em português mesmo, do jeito que você pediria pra um colega

O erro comum deste passo: começar pelo texto da instrução e tentar generalizar depois

Quando você generaliza depois, sobra regra vaga e some o caso real

2. Transforme cada caso num par de entrada e saída

Cada caso de uso vira duas coisas: o que chega e o que sai

Não vira uma frase de regra

O erro comum deste passo: escrever "sempre formate corretamente" em vez de mostrar o formato pronto

Pensa comigo, o que "corretamente" significa pra você? Você sabe, o modelo não sabe

Mostrar o resultado final resolve isso sem discussão

3. Coloque no exemplo o que a regra sozinha não carrega

A documentação usa uma skill de análise no BigQuery como exemplo concreto, e repara no que ela entrega: nomes de tabela, definição dos campos, regras de filtro (como sempre excluir contas de teste) e padrões de consulta comuns

Isso é o tipo de coisa que uma frase de regra não consegue segurar

O erro comum deste passo: exemplo genérico, que serviria pra qualquer projeto do mundo

Se o seu exemplo funcionaria igualzinho no repositório do vizinho, ele não está mostrando o SEU padrão

4. Calibre os graus de liberdade

Esse conceito é ótimo e pouca gente comenta

A documentação descreve os graus de liberdade assim: a especificidade da instrução deve acompanhar a fragilidade e a variabilidade da tarefa

Quando o cenário é de "campo aberto sem obstáculos", onde muitos caminhos levam ao sucesso, você dá direção geral e confia no modelo

Quando a tarefa é frágil, aí sim você fecha o cerco com exemplo detalhado

O erro comum deste passo: engessar uma tarefa que aceita vários caminhos

Skill de campo aberto cheia de exemplo rígido vira camisa de força, e o resultado piora

5. Mantenha o exemplo curto e com material real

A documentação mostra um bom exemplo de extração de texto de PDF que é curto, cerca de 50 tokens, e traz código real, em contraste com explicações verbosas

Essa é a régua: código real ganha de parágrafo explicativo

O erro comum deste passo: escrever um parágrafo explicando o exemplo em vez de simplesmente colocar o exemplo

Se você precisou de três frases pra apresentar o bloco, provavelmente o bloco está fazendo pouco trabalho

6. Quando os exemplos crescerem, use progressive disclosure

Exemplo bom tende a multiplicar, e aí o SKILL.md incha

A solução oficial é o carregamento em camadas: na inicialização, só os metadados (name e description) de todas as skills são pré-carregados, o SKILL.md é lido quando a skill fica relevante, e os arquivos adicionais só são lidos conforme a necessidade

O padrão mostrado na documentação é um SKILL.md enxuto funcionando como índice, apontando pra arquivos separados como FORMS.md, REFERENCE.md e EXAMPLES.md

Você não precisa dos três, escolhe os que fazem sentido pra sua skill

Na blog-stats do nosso exemplo, que não lida com formulário nenhum, ficaria assim:

.claude/skills/blog-stats/
├── SKILL.md
├── EXAMPLES.md
└── REFERENCE.md

O erro comum deste passo: empilhar tudo dentro do SKILL.md porque "é só um arquivo mesmo"

Um dia deixa de ser 😀

Que tipo de exemplo escolher para cada tipo de skill

Nem toda skill pede o mesmo tipo de exemplo, e é aqui que os 2 a 3 casos de uso definidos lá no começo mostram serventia: eles dizem qual formato de exemplo cabe

Skill de consulta a dados:

Aqui o exemplo é a query pronta, com o filtro obrigatório escrito dentro do SQL, não citado na linha de cima

É o espírito do exemplo BigQuery: tabela, campo, regra de filtro e padrão de consulta chegam juntos, no mesmo bloco

Se a regra é excluir contas de teste, o WHERE do exemplo já exclui contas de teste

Skill de formato ou documento:

Aqui o par entrada e saída brilha

Você mostra o material cru como ele chega, feio do jeito que é, e mostra a saída final como ela deve ficar

O modelo não precisa adivinhar a transformação, ele vê a transformação

Skill de tarefa de campo aberto:

Aqui menos é mais

Muitos caminhos levam ao sucesso, então poucos exemplos e direção geral funcionam melhor do que um manual detalhado que fecha portas boas

É o grau de liberdade lá do passo 4 aplicado na escolha do exemplo

Como testar se o exemplo realmente mudou o comportamento

Escrever exemplo sem testar é só achismo com formatação bonita, então bora pro método

A documentação recomenda desenvolver skills com duas instâncias: um Claude A que te ajuda a projetar e refinar as instruções, e um Claude B que usa a skill em tarefas reais, enquanto você observa onde ele erra

É tipo separar quem escreve o enunciado de quem faz a prova, sacou?

1. Rode uma tarefa real com a skill ativa, não uma tarefa inventada pra dar certo
2. Compare a saída com o exemplo que você escreveu, item por item
3. Anote onde a execução divergiu, principalmente as regras que estavam lá e foram ignoradas mesmo assim
4. Promova a regra ignorada a exemplo, em vez de reescrever a frase mais forte

Esse passo 4 é o coração do post

A própria documentação registra uma observação de teste real: ao pedir um relatório regional de vendas, o Claude escreveu a query mas esqueceu de filtrar as contas de teste, mesmo com a skill citando essa regra

Repara que a regra estava escrita e ainda assim não foi seguida

Aumentar o volume da frase não resolve isso, colocar o filtro dentro do exemplo resolve

E lembra do campo lá do começo? É agora que ele entra: o disable-model-invocation no frontmatter desliga a ativação automática e deixa a skill só pra invocação manual

---
name: blog-stats
description: Levanta o desempenho dos posts do blog e monta o resumo da semana
disable-model-invocation: true
---

Assim você controla exatamente quando a skill entra, e não fica na dúvida se o resultado veio dela ou não

Conclusão: de onde tirar exemplos prontos

A ideia do post cabe numa linha: pare de descrever o padrão, mostre o padrão

Regra abstrata é fácil de escrever e fácil de ignorar

Exemplo concreto, com material real do seu projeto, é o que sobrevive na hora da execução

O próximo passo natural é estudar skill de verdade, escrita por quem definiu o formato

Dá uma olhada no repositório público anthropics/skills, e também na skill oficial de desenvolvimento de skills, que vive dentro do toolkit plugin-dev no repositório do Claude Code

Tem ainda o plugin oficial skill-creator, publicado no repositório de plugins oficiais

No Claude Code, plugins de marketplace são instalados pelo comando /plugin install <plugin>@<marketplace>, e a instalação pode ter escopo de usuário, de projeto ou local

Pra leitura seguinte, a Anthropic publicou o artigo Equipping agents for the real world with Agent Skills e um guia completo em PDF, o "The Complete Guide to Building Skills for Claude"

Abre uma skill dessas, pula direto pra seção de exemplos e repara no nível de concretude

Depois faz o teste na sua: pega a regra que o modelo mais ignora e transforma ela num par de entrada e saída

até o próximo post!