📄 SKILL.md: a unidade básica
Toda skill é uma pasta com um arquivo SKILL.md. O nome da pasta vira o ID. É um padrão aberto da Anthropic — a mesma skill funciona em Cowork, Code e (futuramente) em outros agentes compatíveis.
minha-skill/ ← pasta = skill ID ├── SKILL.md ← obrigatório ├── references/ ← opcional (docs longas) │ ├── tabela-x.md │ └── guia-completo.md ├── assets/ ← opcional (imagens, PDFs) │ └── template.png └── scripts/ ← opcional (executáveis) └── render.py
💡 Por que pasta?
Pasta permite anexos. Skill complexa (ex: contract review) precisa de scripts pra gerar PDF, templates de prompt, exemplos. Tudo vai junto.
🧬 YAML frontmatter: name + description
As 2 linhas mais importantes da skill. Sempre carregadas no contexto do Claude — é com elas que ele decide "vou usar esta agora" ou "não, não combina".
Exemplo mínimo (SKILL.md)
--- name: x-insight description: Use this skill when the user wants to scan X (Twitter) and GitHub for trending signals in their niche. Triggers on phrases like "trend report", "what's hot on X", "scan twitter for AI news". Returns a scored ranking of signals with content angle suggestions. --- # X Insight Skill You are a trend intelligence analyst. When invoked, you... [corpo da skill aqui]
✓ Description boa
- ✓Começa com "Use this skill when..."
- ✓Lista frases-gatilho explícitas
- ✓Descreve o output esperado
- ✓Específica, não vaga
✗ Description ruim
- ✗"Ajuda com marketing" (vago)
- ✗"Skill útil pra várias coisas"
- ✗Sem palavras-gatilho
- ✗Muito longa (300+ palavras)
🪟 Progressive disclosure
A arquitetura que faz tudo escalar. Skills carregam em 3 camadas, cada uma só quando necessária.
Camada 1: YAML frontmatter
Sempre no contexto. Custo baixo.
É como o Claude "vê" todas as skills disponíveis. Ele lê só o name + description.
Camada 2: Corpo do SKILL.md
Carrega só quando invocado.
Pode ter centenas de linhas — só pesa quando a skill é chamada pra tarefa.
Camada 3: Anexos (references/, scripts/)
Carregam só quando o corpo pede.
Doc de 50 páginas? Só entra no contexto se a skill referenciar.
📈 Por que isso é importante
Você pode ter 100+ skills instaladas sem estourar contexto. Apenas o description (uma linha) está sempre carregado. Resto é lazy.
📂 Anexos: references, assets, scripts
Skills viram poderosas quando trazem scripts e templates. Não é só texto — é texto + código + dados.
🎒 O que vai em cada pasta
⚡ Exemplo real
A skill contract-review (do repo ai-legal-claude) tem 14 sub-skills + 5 agentes + scripts Python pra gerar PDF profissional. Tudo numa pasta só.
🛠️ skill-creator: a meta-skill
A Anthropic publicou uma skill chamada skill-creator que cria skills pra você. Você nunca precisa escrever YAML/markdown manualmente.
Prompt pra invocar skill-creator
Quero criar uma skill nova chamada "weekly-recap". Objetivo: toda sexta às 18h, ler meu calendário, emails enviados e tarefas concluídas no Notion. Gerar um recap de 1 página com o que aconteceu, métricas e prioridades pra próxima semana. Use o skill-creator pra me entrevistar e gerar o SKILL.md.
🔄 Como funciona
- skill-creator te faz 5-10 perguntas pra capturar contexto
- Gera o SKILL.md com name, description e corpo
- Sugere references/ e scripts/ se fizer sentido
- Roda evals automáticos pra confirmar que funciona
- Salva na sua pasta de skills
🧪 Run evals: testar a skill
Skill ruim piora o output. Por isso a Anthropic embutiu run evals: você compara o output com a skill vs sem a skill. Se a skill não ganha, descarte.
🔬 O que evals medem
- Precisão: a skill dispara quando deveria? Não dispara quando não deveria?
- Qualidade: o output é melhor do que sem a skill?
- Eficiência: usa menos tokens? Resolve em menos passos?
- Regressão: quebrou alguma outra skill que dependia dela?
⚠️ Atenção
Skills sem evals são apostas. Quando uma skill da comunidade pede run evals na primeira instalação — rode. Não pule. É barato e evita instalar lixo.
📚 Resumo do Módulo
Próximo Módulo:
1.4 — 🔌 Conectores e MCP