Guia Prático para Criar Habilidades do Claude: Estrutura, Gatilhos e Scripts

O que são as Habilidades Claude e Como Funcionam

As Habilidades Claude são manuais de instrução que automatizam tarefas específicas, distintas dos Projetos (bases de conhecimento) e do Model Context Protocol (camada de conexão para dados em tempo real). Se você digitou as mesmas instruções no início de mais de três conversas, essa é uma habilidade implorando para ser criada.

Estrutura e Configuração da Habilidade

Uma habilidade é uma pasta contendo um arquivo chamado SKILL.md. A estrutura básica é:

nome-da-sua-habilidade/
├── SKILL.md
└── references/
    └── seu-ref.md

Coloque a pasta em ~/.claude/skills/ na sua máquina. O Claude a encontra automaticamente.

Gatilhos YAML: O Mecanismo de Ativação

No topo do SKILL.md, escreva metadados entre as linhas --- para dizer ao Claude quando ativar. Exemplo:

---
name: limpador-csv
description: Transforma arquivos CSV bagunçados em planilhas limpas. Use esta habilidade sempre que o usuário disser 'limpe este CSV', 'corrija os cabeçalhos', 'formate estes dados' ou 'organize esta planilha'. NÃO use para PDFs, documentos do Word ou arquivos de imagem.
---

Siga três regras: escreva na terceira pessoa, liste frases de gatilho exatas e defina limites negativos. O campo de descrição é a linha mais importante em toda a habilidade—uma descrição fraca significa que a habilidade nunca será acionada.

Quando Instruções Não São Suficientes: Diretório de Scripts

Instruções em inglês simples lidam com julgamento, linguagem, formatação e decisões. Para tarefas que precisam de computação real, adicione uma pasta scripts/.

Use instruções para: "reescreva isso na voz da nossa marca" ou "categorize estas anotações de reunião".

Use scripts para: "calcule a média móvel destes números", "analise este XML e extraia campos específicos" ou "redimensione todas as imagens nesta pasta para 800x600".

Estrutura de pasta para uma habilidade usando ambos:

analisador-de-dados/
├── SKILL.md
├── references/
│   └── modelo-analise.md
└── scripts/
    ├── analisar-csv.py
    └── calcular-estatisticas.py

Dentro do SKILL.md, referencie scripts assim:

## Fluxo de Trabalho
1. Leia o arquivo CSV enviado para entender sua estrutura.
2. Execute scripts/analisar-csv.py para limpar os dados:
   - Comando: `python scripts/analisar-csv.py [arquivo_entrada] [arquivo_saida]`
   - Isso remove linhas vazias, normaliza cabeçalhos e aplica tipos de dados.
3. Execute scripts/calcular-estatisticas.py nos dados limpos:
   - Comando: `python scripts/calcular-estatisticas.py [arquivo_limpo]`
   - Isso gera: média, mediana, desvio padrão e outliers para cada coluna numérica.
4. Leia a saída estatística e escreva um resumo legível seguindo o modelo em references/modelo-analise.md. Destaque quaisquer anomalias ou outliers que preocupariam um leitor não técnico.

Scripts lidam com computação; instruções lidam com julgamento. Uma regra para scripts: um script, uma tarefa. analisar-csv.py não deve também calcular estatísticas. Mantenha-os focados, aceite caminhos de arquivo como argumentos, nunca codifique caminhos e sempre inclua tratamento de erros para que o Claude possa ler falhas e comunicá-las claramente.

Referências: A Regra de Um Nível de Profundidade

Se uma habilidade precisa de um guia de marca ou modelo, coloque-o em references/ e vincule-o do SKILL.md. Nunca tenha arquivos de referência vinculando a outros arquivos de referência—o Claude truncará sua leitura e perderá coisas. Apenas um nível de profundidade.

nome-da-sua-habilidade/
├── SKILL.md
└── references/
    └── guia-voz-marca.md ← vincule a isto do SKILL.md ← nunca vincule a outro arquivo daqui

No SKILL.md: Antes de iniciar a tarefa, leia o guia de voz da marca em references/guia-voz-marca.md

Orquestração de Múltiplas Habilidades: Prevenindo Conflitos

Uma vez que você tenha cinco ou mais habilidades implantadas, os conflitos começam—como o aplicador de voz da marca sendo acionado quando você queria o redator de e-mails. Três regras impedem isso:

• Regra 1: Territórios não sobrepostos. Cada habilidade possui um domínio claramente definido (ex.: aplicador de voz da marca lida com conformidade de voz, redator de e-mails lida com composição, reutilizador de conteúdo lida com transformação de formato). Sem vazamentos.
• Regra 2: Limites negativos agressivos.