Como criar Skills para o Claude: guia prático e boas práticas

O que são Agent Skills

Uma skill é uma pasta com um arquivo SKILL.md que ensina o Claude a fazer uma tarefa específica do seu jeito, e que ele carrega sozinho quando a tarefa aparece. Pense nela como o guia de onboarding que você entregaria para um dev novo no time: instruções, exemplos, scripts e material de referência, tudo organizado em arquivos.

A diferença para um prompt comum é a reutilização. Um prompt vale para uma conversa; uma skill fica instalada e é usada automaticamente sempre que o pedido combina com ela, sem você repetir as mesmas orientações toda vez.

Por que vale a pena criar as suas:

• Especializar o Claude no seu domínio: padrões do seu projeto, regras de negócio, convenções do time.
• Parar de repetir contexto: escreve uma vez, o Claude usa sempre que for relevante.
• Combinar capacidades: várias skills podem atuar juntas numa tarefa de várias etapas.

A Anthropic já oferece skills prontas para documentos (Word, Excel, PowerPoint e PDF). Este tutorial foca nas skills personalizadas, as que você mesmo escreve.

Como as skills funcionam

O Claude carrega uma skill em camadas, só quando precisa: é a chamada progressive disclosure. Por isso você pode instalar dezenas de skills sem lotar o contexto.

Na prática, o fluxo é este:

1. Na inicialização, o nome e a descrição de todas as skills entram no system prompt.
2. Você faz um pedido. O Claude compara o pedido com as descrições.
3. Se uma combina, ele lê o SKILL.md daquela skill pelo sistema de arquivos.
4. Se as instruções apontam para outro arquivo (um REFERENCE.md, por exemplo), ele lê esse arquivo só se a tarefa exigir.
5. Scripts são executados, não lidos: só a saída deles entra no contexto.

Onde as skills rodam

As skills não sincronizam entre superfícies: uma skill enviada ao claude.ai precisa ser enviada separadamente para a API, e vice-versa.

Anatomia de uma skill

O mínimo é uma pasta com um SKILL.md; todo o resto é opcional e só entra quando a skill cresce. Uma skill mais completa costuma ter esta cara:

minha-skill/
├── SKILL.md            # obrigatório: frontmatter + instruções principais
├── REFERENCE.md        # referência detalhada, lida só quando necessário
├── EXAMPLES.md         # exemplos de entrada e saída
├── reference/
│   ├── financeiro.md   # conteúdo separado por domínio
│   └── vendas.md
└── scripts/
    └── validar.py      # executado pelo Claude, não lido

O arquivo SKILL.md

Ele tem duas partes: um frontmatter YAML com os metadados e um corpo em Markdown com as instruções.

---
name: nome-da-skill
description: O que a skill faz e quando usar. Use quando o usuário pedir X, mencionar Y ou trabalhar com arquivos Z.
---

# Nome da skill

## Instruções
[Passo a passo claro para o Claude seguir]

## Exemplos
[Exemplos concretos de uso]

Regras do frontmatter

No Claude Code existe ainda o campo opcional allowed-tools, que limita as ferramentas que a skill pode usar. Ele só vale na CLI do Claude Code; o Agent SDK o ignora.

Os três tipos de conteúdo

• Instruções (arquivos .md): orientação flexível, fluxos de trabalho, regras.
• Código (scripts): operações determinísticas e confiáveis; só a saída gasta tokens.
• Recursos (schemas, templates, documentação): material de consulta, sem custo até ser lido.

Passo a passo: sua primeira skill

Vamos criar uma skill que padroniza mensagens de commit no formato Conventional Commits, em português. É um caso pequeno, útil no dia a dia e fácil de testar.

1. Descubra o que o Claude ainda não sabe

Antes de escrever, peça ao Claude algumas mensagens de commit sem skill nenhuma. Anote o que sai diferente do padrão do seu time: idioma, tipos usados, tamanho da linha, uso de escopo. São essas lacunas que a skill precisa cobrir, e nada além delas.

2. Crie a pasta

mkdir -p ~/.claude/skills/escrevendo-commits

O nome da pasta e o campo name seguem a mesma regra: minúsculas, números e hífens.

3. Escreva o SKILL.md

---
name: escrevendo-commits
description: Gera mensagens de commit no padrão Conventional Commits em português, analisando o git diff. Use quando o usuário pedir uma mensagem de commit, revisar mudanças em stage ou mencionar commit.
---

# Mensagens de commit

## Formato

```
tipo(escopo): resumo no imperativo, até 72 caracteres

Corpo opcional explicando o porquê da mudança.
```

Tipos permitidos: feat, fix, refactor, docs, test, chore.
Escreva sempre em português. Sem ponto final no resumo.

## Exemplos

Mudança: endpoint de login com JWT
```
feat(auth): adiciona login com token JWT

Cria a rota POST /login e o middleware de validação do token.
```

Mudança: data errada nos relatórios
```
fix(relatorios): corrige fuso horário na formatação de datas
```

Repare no que não está ali: nenhuma explicação sobre o que é git ou para que serve um commit. O Claude já sabe disso; a skill só traz o que é específico do seu padrão.

4. Teste

No Claude Code, faça uma alteração qualquer no repositório e peça: "escreve a mensagem de commit dessas mudanças". Se a skill for acionada, a mensagem já sai no formato definido. Se não for, o problema quase sempre está na description.

5. Faça a skill crescer só se precisar

Se o padrão do time tiver muitas regras (lista de escopos por módulo, regras de breaking change), mova esse detalhe para um REFERENCE.md e aponte para ele no SKILL.md:

**Escopos válidos por módulo**: veja [REFERENCE.md](REFERENCE.md)

Instalando e testando em cada superfície

Claude Code. Coloque a pasta em ~/.claude/skills/ para uso pessoal ou em .claude/skills/ dentro do repositório para o time inteiro. Não precisa de upload: o Claude descobre as skills sozinho. Para conferir se estão no lugar certo:

ls ~/.claude/skills/*/SKILL.md
ls .claude/skills/*/SKILL.md

claude.ai. Compacte a pasta da skill em .zip e envie pelas configurações da conta, na área de recursos. Exige plano pago com execução de código ativada. A skill fica disponível só para o seu usuário: cada pessoa do time precisa enviar a sua cópia.

Claude API. Envie a skill pelos endpoints /v1/skills e referencie o skill_id no parâmetro container, junto com a code execution tool. A skill fica disponível para todo o workspace. Lembre que o container da API não tem rede e não instala pacotes em tempo de execução, então use só o que já vem instalado.

Claude Agent SDK. As skills ficam nas mesmas pastas .claude/skills/ do Claude Code. Se ela não for acionada, confira se a ferramenta Skill está liberada em allowed_tools e se a descrição tem as palavras-chave certas.

Como saber se funcionou

• Faça um pedido que deveria acionar a skill e veja se o Claude lê o SKILL.md.
• Faça um pedido parecido que não deveria acioná-la e veja se ela fica de fora.
• Se ela não dispara, reescreva a description com os termos que o usuário realmente usa.

Boas práticas

Uma boa skill é curta, bem organizada e testada com uso real. Estas são as práticas que mais fazem diferença.

1. Seja conciso: o Claude já é inteligente

O contexto é compartilhado com o system prompt, o histórico da conversa e as outras skills. Cada parágrafo precisa justificar o espaço que ocupa. Antes de manter um trecho, pergunte: o Claude realmente precisa disso, ou já sabe?

PDF é um formato de arquivo muito comum que contém texto e imagens.
Para extrair o texto, você vai precisar de uma biblioteca. Existem várias...

## Extrair texto de PDF
Use pdfplumber:

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

Regra prática: mantenha o corpo do SKILL.md com menos de 500 linhas. Passou disso, divida em arquivos.

2. Escreva uma descrição que o Claude consiga achar

A descrição é o único texto que o Claude vê antes de decidir usar a skill, muitas vezes no meio de dezenas de outras.

• Diga o que a skill faz e quando usar.
• Inclua as palavras que o usuário de fato digita ("planilha", ".xlsx", "commit").
• Escreva em terceira pessoa, porque o texto vai para o system prompt: "Gera relatórios a partir de planilhas", e não "Eu posso te ajudar com planilhas".

3. Dê um nome claro e consistente

Prefira verbos no gerúndio, que descrevem a atividade: processando-pdfs, analisando-planilhas, escrevendo-commits. Evite nomes vagos como helper, utils ou dados, e mantenha o mesmo padrão em todas as suas skills.

4. Ajuste o grau de liberdade ao risco da tarefa

A analogia da documentação oficial ajuda: numa ponte estreita com abismo dos dois lados, você dá o caminho exato; num campo aberto, só a direção.

5. Organize com progressive disclosure

Trate o SKILL.md como um índice que aponta para o detalhe. Três padrões funcionam bem:

• Guia + referências: o básico no SKILL.md, com links para FORMS.md, REFERENCE.md, EXAMPLES.md.
• Por domínio: reference/financeiro.md, reference/vendas.md. Uma pergunta de vendas não carrega nada de financeiro.
• Detalhe condicional: o caso comum no corpo; o caso raro ("para alterações rastreadas, veja REDLINING.md") em arquivo separado.

Dois cuidados: mantenha as referências a um nível de profundidade a partir do SKILL.md (arquivo que aponta para arquivo que aponta para arquivo tende a ser lido pela metade) e coloque um sumário no topo de qualquer referência com mais de 100 linhas.

6. Use fluxos com checklist e ciclos de validação

Para tarefas de várias etapas, escreva os passos em ordem e ofereça um checklist que o Claude copia e marca conforme avança. Para tarefas em que a qualidade é crítica, inclua um ciclo: validar, corrigir, validar de novo, e só seguir quando passar.

Progresso:
- [ ] 1. Analisar o formulário (rodar analyze_form.py)
- [ ] 2. Montar o mapeamento de campos (editar fields.json)
- [ ] 3. Validar o mapeamento (rodar validate_fields.py)
- [ ] 4. Preencher o formulário (rodar fill_form.py)
- [ ] 5. Verificar o resultado (rodar verify_output.py)

7. Prefira scripts para o que é determinístico

Um script pronto é mais confiável que código gerado na hora, economiza tokens (só a saída entra no contexto) e garante o mesmo resultado sempre. Ao escrever scripts:

• Resolva os erros no script, em vez de deixar o Claude descobrir o que fazer com uma exceção.
• Justifique as constantes com um comentário. Um TIMEOUT = 47 sem explicação não ajuda ninguém.
• Deixe claro se o Claude deve executar o script ("rode validar.py") ou lê-lo como referência.
• Liste as dependências e não presuma que estão instaladas.
• Em operações em lote ou destrutivas, use plano verificável: o Claude gera um arquivo de plano (changes.json), um script valida, e só então as mudanças são aplicadas.

8. Comece pelas avaliações

Crie os testes antes de escrever muita documentação:

1. Rode o Claude em tarefas reais sem a skill e anote onde ele falha.
2. Monte pelo menos três cenários de teste que cubram essas falhas.
3. Meça o desempenho sem a skill (linha de base).
4. Escreva o mínimo de instrução para resolver as falhas.
5. Rode os testes de novo, compare e refine.

Não existe um executor de avaliações embutido; você monta o seu, mesmo que seja um JSON simples com pedido, arquivos e comportamentos esperados.

9. Use o próprio Claude para escrever a skill

Um fluxo que funciona muito bem: resolva a tarefa conversando com um Claude ("Claude A"), perceba o contexto que você teve que repetir e peça para ele transformar isso numa skill. Depois teste com uma instância nova ("Claude B") e leve o que deu errado de volta para o Claude A. Repita até a skill se comportar como você espera.

10. Teste com todos os modelos que vai usar

O que funciona no Opus pode precisar de mais detalhe no Haiku. Se a skill vai rodar em modelos diferentes, teste em cada um.

Erros comuns e segurança

Segurança

Uma skill dá ao Claude instruções e código para executar, então trate a instalação de uma skill como a instalação de um software.

• Use só skills que você mesmo escreveu ou que vêm de fontes confiáveis, como a própria Anthropic.
• Antes de instalar uma skill de terceiros, leia todos os arquivos: SKILL.md, scripts, imagens e recursos.
• Desconfie de chamadas de rede inesperadas, acessos a arquivos sem relação com o propósito da skill ou operações que não batem com a descrição.
• Skills que buscam conteúdo em URLs externas são as mais arriscadas: o conteúdo baixado pode trazer instruções maliciosas, mesmo que a skill em si seja legítima.
• Nunca coloque segredos (tokens, senhas, chaves de API) dentro dos arquivos da skill.

Checklist antes de publicar

Qualidade

• A descrição é específica, em terceira pessoa, e diz o que faz e quando usar
• O corpo do SKILL.md tem menos de 500 linhas
• O detalhe extra está em arquivos separados, a um nível do SKILL.md
• Referências longas têm sumário no topo
• Não há informação com prazo de validade fora de uma seção de legado
• A terminologia é a mesma do começo ao fim
• Os exemplos são concretos
• Os fluxos têm passos claros e, quando importa, um ciclo de validação

Código e scripts

• Os scripts tratam os próprios erros
• Nenhuma constante sem justificativa
• As dependências estão listadas e disponíveis na superfície de destino
• Todos os caminhos usam barra normal

Testes

• Pelo menos três cenários de avaliação
• Testada em todos os modelos que vão usá-la
• Testada com pedidos reais, inclusive pedidos que não deveriam acioná-la

Referências

• Agent Skills: visão geral (documentação oficial)
• Skill authoring best practices (documentação oficial)
• Agent Skills no Agent SDK
• Equipping agents for the real world with Agent Skills (blog de engenharia da Anthropic)
• Repositório de skills open source da Anthropic