📋 O framework de 6 passos

Novo aqui? O front matter é o bloco de metadados no topo do `skill.md`, entre duas linhas `---`, no formato `chave: valor`. É lá que moram o name (o identificador da skill) e a description (o texto que o agente lê pra decidir se usa essa skill ou não). O passo 1 é escolher os dois com cuidado.

Pense numa receita de bolo: o título na capa do caderno ("Bolo de cenoura da vó") já avisa quando você vai abrir aquela página. O `name` é esse título — curto, sem espaço, tipo relatorio-mensal-cliente. A description é o resumo na contracapa: quando usar, com que situação ela combina. Ela é aprofundada inteira no módulo 3.4 — aqui o que importa é saber que ela existe e mora no passo 1.

Logo depois do front matter, a skill precisa de uma frase clara dizendo o que ela ENTREGA. Não "ajuda com relatórios" (vago), mas "gera um PDF de relatório mensal a partir da planilha de vendas do cliente, pronto pra enviar por e-mail" (concreto, com resultado final nomeado). É o equivalente à foto do bolo pronto na primeira página da receita — você sabe exatamente aonde vai chegar antes de ler o passo a passo.

Ambiguidade aqui custa caro: se o objetivo permite duas leituras, o agente vai escolher uma na hora errada. "Organiza meus arquivos" pode significar renomear, mover pra pastas por data, ou apagar duplicados — três coisas bem diferentes. Escreva o objetivo como se fosse a última frase que alguém vai ler antes de aprovar.

Aqui mora o corpo da skill: a sequência numerada de ações que o agente segue. Cada item precisa ser verificável — dá pra checar se aconteceu ou não. "1. Abrir a planilha `vendas.xlsx`. 2. Somar a coluna 'total' por região. 3. Gerar um gráfico de barras. 4. Exportar em PDF." Cada número é um checklist de piloto: antes de decolar, ele confere item por item, na ordem, sem pular.

Legenda: os 6 passos formam um pipeline que fecha em círculo — depois do passo 6 (melhoria), a skill volta pro passo 1 na próxima execução, já um pouco melhor.

Nem tudo precisa estar no `skill.md`. Detalhes longos — tabelas de códigos de erro, exemplos extensos, modelos de documento — vão em arquivos separados dentro da pasta da skill (geralmente uma subpasta references/), e o `skill.md` só APONTA pra eles quando for preciso. Isso é o carregamento em 3 níveis do módulo 3.2 aplicado na prática: o agente só lê a referência se a situação pedir, então o `skill.md` principal fica enxuto e barato de carregar toda vez.

O passo mais pulado — e o que mais causa dor de cabeça quando falta. Regras são restrições explícitas: o que o agente NUNCA deve fazer sozinho, mesmo que pareça o caminho mais rápido. "Não enviar o e-mail sem eu revisar antes." "Não sobrescrever o arquivo original — sempre criar uma cópia." "Não apagar linhas da planilha, só marcar como processadas." Sem essas travas, um agente eficiente e sem contexto vai tomar o atalho perigoso, porque tecnicamente funciona — só que não é o que você queria.

Uma skill não nasce perfeita — assim como ninguém acerta a receita de bolo na primeira tentativa. O passo 6 é o hábito de revisar depois de usar algumas vezes: o que deu errado? O agente hesitou em algum ponto? Fez algo que você não queria? Cada resposta vira uma linha nova nos passos 3 ou 5 (mais um passo, ou mais uma regra). É assim que uma skill vai de "funciona às vezes" pra "confiável sempre".

---
name: relatorio-mensal-cliente          # 1. nome e gatilho
description: Gera o PDF do relatório mensal de vendas quando o
  usuário pedir "relatório mensal", "fechamento do mês" ou "PDF de vendas".
---

## Objetivo                              # 2. objetivo em uma frase
Gerar o PDF do relatório mensal de vendas a partir de vendas.xlsx,
com gráfico por região, pronto para enviar por e-mail.

## Passos                                # 3. passo a passo verificável
1. Abrir vendas.xlsx e validar que a coluna "total" existe.
2. Somar o total por região.
3. Gerar gráfico de barras (uma barra por região).
4. Exportar como PDF em saida/relatorio-<mes>.pdf.

## Referências                          # 4. referências
Se o cliente for "Cliente X", ver references/regras-cliente-x.md
antes do passo 3 (ele usa moeda diferente).

## Regras                                # 5. regras
- Nunca sobrescrever vendas.xlsx.
- Nunca enviar o PDF por e-mail sozinho — sempre aguardar aprovação.

## Histórico de ajustes                  # 6. ciclo de melhoria
- 2026-06: adicionada regra de não sobrescrever (aconteceu 1x).
- 2026-07: cliente X precisou de referência separada (moeda).

Crie um skill.md esqueleto para uma skill chamada
<nome-da-skill>, cujo objetivo é <o que ela deve entregar>.
Estruture com os 6 elementos, cada um comentado:
1) front matter com name e description (gatilho),
2) seção Objetivo em uma frase,
3) seção Passos numerada e verificável,
4) seção Referências (aponte para references/ se precisar),
5) seção Regras com pelo menos 2 restrições explícitas de "não faça",
6) seção Histórico de ajustes, vazia, pronta para eu preencher
   depois da primeira execução.