🧭 O caminho do zero ao SKILL.md
Criar uma skill é um trajeto de seis paradas: capturar intent → frontmatter → corpo → pastas → empacotar → iterar. Neste módulo você percorre da pasta vazia até o arquivo pronto. A iteração (testar e otimizar a description) é o tema da Trilha 4 — aqui o foco é a montagem.
Comece minúsculo
Um SKILL.md válido tem só duas partes: frontmatter com name + description, e um corpo Markdown. Pastas são opcionais — só crie quando o conteúdo pedir. Não monte scripts/ no dia um.
🏷️ Passo 1 — frontmatter: name kebab-case
O name é o identificador. Regra única e inegociável: kebab-case minúsculo, igual ao nome da pasta. Sem espaços, sem maiúsculas, sem underscores.
✗ Names quebrados
- ✗ PDF Extractor
- ✗ pdf_extractor
- ✗ PdfExtractor
- ✗ minha-skill-v2-final
✓ Names corretos
- ✓ pdf-extractor
- ✓ frontend-design
- ✓ skill-creator
- ✓ supabase
💡 Dica
O nome da pasta DEVE bater com o name. Se a pasta é pdf-extractor/, o frontmatter é name: pdf-extractor. Divergência quebra o carregamento.
🎣 Passo 2 — description: o gatilho
A description é o único texto sempre carregado e o que faz a skill disparar. Siga a fórmula: [O QUE faz] + [QUANDO usar] + [GATILHOS concretos]. Seja pushy — Claude subdispara por padrão.
a fórmula aplicada (exemplo de uma skill nova):
description: Extract structured data from PDF invoices and receipts into JSON. Use this skill whenever the user uploads a PDF invoice/receipt, asks to "parse", "extract fields", or "read" a financial document, or mentions OCR on a scanned bill.
O QUE faz
"Extract structured data from PDF invoices..." — começa com verbo e diz o resultado.
QUANDO usar
"Use this skill whenever the user uploads a PDF invoice..." — a condição de disparo.
GATILHOS concretos
"parse", "extract fields", "read", "OCR" — palavras-chave que o usuário realmente digita.
~100 palavras é o teto
A metadata (name + description) é o Nível 1 do progressive disclosure e fica SEMPRE no contexto. Mantenha em torno de 100 palavras: assertiva o bastante para disparar, enxuta o bastante para não pesar em cada conversa.
📝 Passo 3 — o corpo: imperativo, When to Use, Steps
O corpo é Markdown em modo imperativo ("Read the file", "Run the script"), explicando o porquê em vez de gritar MUSTs em maiúscula. Uma estrutura que funciona: título, uma linha do que a skill faz, When to Use, Steps numerados e exemplos de output.
esqueleto do corpo:
# PDF Invoice Extractor
Extracts fields from PDF invoices into clean JSON.
## When to Use
Use when the user provides a PDF invoice and asks
to extract fields, parse, or read it.
## Steps
1. Run `python scripts/extract.py <file.pdf>`.
2. Validate the JSON against the schema below.
3. Return the JSON; flag any missing field.
## Output Format
{ "vendor": str, "total": number, "date": str }
✗ Corpo ruim
- ✗"YOU MUST ALWAYS..." gritado em caps
- ✗Parágrafos longos sem passos
- ✗Sem dizer quando usar
✓ Corpo bom
- ✓Imperativo claro + o porquê
- ✓Steps numerados, acionáveis
- ✓When to Use + Output Format explícitos
📁 Passo 4 — quando criar cada pasta
As pastas são opcionais e nascem da necessidade, não da estética. Crie só quando o gatilho abaixo aparecer:
scripts/ — código determinístico
Crie quando uma tarefa tem mesma entrada → mesma saída (converter arquivo, validar schema). Mais confiável que instruções e executa sem carregar o código no contexto.
references/ — docs sob demanda
Crie quando o corpo cresceria além de 500 linhas com detalhes que só importam em casos específicos. O agente lê só o arquivo relevante.
assets/ — arquivos de saída
Crie quando a skill produz algo a partir de um template (HTML, fonte, ícone, boilerplate). São arquivos usados no output, não lidos como instrução.
a árvore final da skill de exemplo:
pdf-extractor/
├── SKILL.md # frontmatter + corpo
├── scripts/
│ └── extract.py # roda sem ir pro contexto
├── references/
│ └── field-map.md # lido só em casos raros
└── assets/
└── report.html # template de saída
💡 Dica
Não crie pastas vazias "para o futuro". Cada arquivo deve ter um ponteiro correspondente no corpo do SKILL.md dizendo quando lê-lo ou executá-lo.
📄 Passo 5 — template completo para copiar
Junte tudo. Este é um SKILL.md inteiro, pronto para colar num arquivo, trocar os nomes e começar. Cobre frontmatter, When to Use, Steps, Output Format e ponteiros para as pastas.
SKILL.md — template completo:
---
name: pdf-extractor
description: Extract structured data from PDF
invoices and receipts into JSON. Use this skill
whenever the user uploads a PDF invoice/receipt,
asks to "parse", "extract fields", or "read" a
financial document, or mentions OCR on a bill.
metadata:
author: seu-usuario
version: "0.1.0"
---
# PDF Invoice Extractor
Extracts fields from PDF invoices into clean,
validated JSON. Built for accounts-payable flows.
## When to Use
Use when the user provides a PDF invoice or
receipt and asks to extract, parse, or read its
fields. Do NOT use for plain-text data or images
without a document layout.
## Steps
1. Run `python scripts/extract.py <file.pdf>` to
pull raw fields. The script handles OCR.
2. Validate the result against the schema in
`references/field-map.md` — read it only if a
field is missing or ambiguous.
3. If the user wants a report, fill the template
`assets/report.html` with the JSON.
4. Return the JSON and flag any field you could
not extract. Never invent values.
## Output Format
```json
{ "vendor": "string", "total": 0.00,
"date": "YYYY-MM-DD", "line_items": [] }
```
## Notes
Explain to the user which fields were uncertain so
they can verify — accuracy matters more here than
speed.
Pronto — agora teste
Salve como pdf-extractor/SKILL.md, crie as pastas citadas e você tem uma skill instalável. O passo 6 — testar, avaliar e otimizar a description num loop — é exatamente o tema da Trilha 4. O 3.5, a seguir, mostra como deixar a estrutura multi-arquivo realmente afiada.
✅ Resumo do Módulo
Próximo:
Módulo 3.5 — 🚀 Dicas avançadas: progressive disclosure de verdade, roteamento por domínio, scripts que rodam sem contexto e como manter o SKILL.md abaixo de 500 linhas.