Criando uma Skill na prática: o que acontece no caminho

Escrever uma Skill parece simples até o momento de decidir o que exatamente vai dentro do arquivo. O formato é curto, um SKILL.md com metadados no topo e instruções no corpo, mas as decisões que aparecem no caminho não são triviais.

O ponto de partida: um arquivo com dois campos obrigatórios

Toda Skill exige um SKILL.md com frontmatter YAML contendo name e description. O name aceita só letras minúsculas, números e hífen, tem limite de caracteres e não pode usar palavras reservadas como “claude” ou “anthropic”. A description precisa dizer duas coisas ao mesmo tempo: o que a Skill faz e quando ela deve ser usada.

---
name: revisao-de-commits
description: Gera mensagens de commit descritivas a partir de um diff. Use quando o pedido envolver escrever mensagem de commit ou revisar mudanças staged.
---

Essa segunda parte da descrição costuma ser a que mais gente esquece. Uma descrição como “ajuda com commits” não dá contexto suficiente para o agente decidir se aquela Skill se aplica à tarefa atual, especialmente quando existem várias Skills instaladas ao mesmo tempo.

Delimitar o escopo é mais difícil do que escrever a instrução

Antes de escrever qualquer instrução, existe uma decisão anterior: o que essa Skill cobre e o que fica de fora dela. Uma Skill ampla demais, tentando resolver “qualquer coisa relacionada a banco de dados”, tende a ficar vaga justamente nos pontos onde precisaria ser específica. Uma Skill estreita demais, cobrindo só um caso muito particular, multiplica a quantidade de Skills necessárias para cobrir um domínio inteiro.

Não existe fórmula fixa para esse equilíbrio. O critério mais prático é perguntar se a Skill continua descritível numa frase clara de “o que faz e quando usar”. Se a resposta exige “e também” repetidas vezes, é sinal de que o escopo cresceu além do que uma única Skill deveria cobrir.

O corpo do SKILL.md: menos explicação do que parece necessário

Depois do frontmatter vem o conteúdo principal, e aqui o instinto mais comum é explicar demais. O modelo que vai usar a Skill já tem conhecimento geral considerável. Repetir definições básicas ou contexto que qualquer modelo atual já possui só consome espaço que poderia ir para a parte realmente específica daquele domínio.

## Extrair texto de PDF

Use pdfplumber:

\`\`\`python
import pdfplumber
with pdfplumber.open("arquivo.pdf") as pdf:
    texto = pdf.pages[0].extract_text()
\`\`\`

Esse exemplo funciona porque assume que quem vai executar a Skill já sabe o que é um PDF e como uma biblioteca Python se importa. A instrução vai direto ao ponto específico que precisa ser transmitido.

Referências, scripts e o que fica fora do arquivo principal

Quando o conteúdo cresce além do que cabe confortavelmente num único arquivo, a estrutura de uma Skill permite dividir em arquivos auxiliares, referenciados a partir do SKILL.md principal. Um arquivo de referência mais longo, um guia específico para um subcaso, ou um script utilitário que executa uma operação determinística em vez de depender do modelo gerar aquele código toda vez.

Essa divisão só compensa quando existe conteúdo suficiente para justificá-la. Uma Skill pequena, resolvida em poucas linhas, não precisa de arquivo auxiliar nenhum. A estrutura em camadas existe para quando o domínio é grande o bastante para tornar um arquivo único difícil de navegar, não como padrão obrigatório para toda Skill.

O resultado depende de testar com um pedido real

Uma Skill escrita e nunca usada é só uma teoria sobre o que seria útil. A forma mais confiável de saber se o escopo, a descrição e as instruções fazem sentido é submeter a Skill a um pedido real e observar se ela é acionada quando deveria, e se as instruções levam ao resultado esperado sem exigir intervenção manual no meio do caminho. Ajustar depois dessa observação costuma revelar mais problema do que qualquer revisão feita só lendo o arquivo.