🎯 O que vamos construir
Vamos criar a skill gerar-ata: você cola no chat as anotações soltas que tomou durante uma reunião — mesmo bagunçadas, com abreviação e frase cortada — e o agente devolve uma ata formatada, com data, participantes, decisões e próximos passos separados em seções. É um exemplo pequeno de propósito, mas o procedimento de construção é exatamente o mesmo que você vai usar pra qualquer skill maior.
Por que esse exemplo e não outro mais chamativo? Porque ele tem entrada clara (o texto solto), saída clara (a ata formatada) e regras que dá pra testar na hora — os três ingredientes de uma primeira skill que ensina bem sem te afogar em detalhe.
💡 Conceito Principal
- •Entrada: anotações soltas de reunião, coladas no chat.
- •Saída: ata formatada com data, participantes, decisões, próximos passos.
- •O procedimento de construção vale pra qualquer skill futura sua.
📁 O esqueleto de pastas
Toda skill começa com uma pasta. Dentro dela, no mínimo um arquivo `skill.md`. Como esta é uma skill pessoal,
que você quer usar em qualquer projeto (mais sobre essa escolha no módulo 3.5), ela vai morar em
~/.claude/skills/gerar-ata/ — o `~` é um atalho pra "pasta pessoal do
seu usuário" no terminal (a caixa de texto que dá ordens direto ao computador).
Legenda: da ideia à pasta com os 4 pedaços do `skill.md`, até o teste real e o ajuste que fecha o ciclo.
✏️ Copy-run — criar a pasta e o arquivo
Objetivo: pedir ao Claude Code pra criar a estrutura de pastas da skill.
Crie a pasta ~/.claude/skills/<nome-da-sua-skill>/ com um
arquivo skill.md vazio dentro. Não escreva conteúdo ainda,
só a estrutura.Como verificar: rode ls ~/.claude/skills/ no terminal e confirme que a pasta com o arquivo `skill.md` aparece.
🏷️ Escrevendo o front matter
Novo aqui? Front matter é o bloco de metadados no topo do `skill.md`, entre duas linhas com três traços (`---`). É ali que ficam `name` (o nome da skill) e `description` (a frase que o agente compara com o seu pedido pra decidir se usa essa skill — aprofundado no módulo 3.4). Sem front matter, o agente não sabe nem que a skill existe.
skill.md — cabeçalho
---
name: gerar-ata
description: Transforma anotações soltas de reunião (coladas no
chat) em uma ata formatada com data, participantes, decisões
e próximos passos. Use quando o usuário colar anotações de
reunião ou pedir "gera a ata", "organiza essa reunião".
---✓ Description específica
- ✓Diz o que a skill entrega
- ✓Diz quando usar, com frases reais do usuário
✗ Description vaga
- ✗"Ajuda com reuniões" — não diz o quê nem quando
- ✗O agente pode nunca disparar
📝 Escrevendo o corpo
Depois do front matter vem o corpo em markdown normal: o passo a passo que o agente segue quando a skill dispara. Escreva como se estivesse orientando um estagiário atento — curto, numerado, sem floreio.
Leia as anotações coladas
Identifique data (se não tiver, pergunte), participantes citados, decisões tomadas, pendências.
Monte a ata em 4 seções fixas
Data e participantes / Pauta / Decisões / Próximos passos com responsável.
Mostre a ata e pergunte se falta algo
Nunca invente decisão que não estava no texto original.
💡 Dica Prática
Se o corpo passar de 1-2 páginas de instrução muito detalhada, é sinal de mover parte pra um arquivo de referência (módulo 3.1 e 3.2) em vez de inchar o `skill.md` principal.
🧪 Testar e ajustar
Skill escrita não é skill pronta — ela só prova valor quando disparada de verdade, com um caso real. Cole anotações de uma reunião de mentira e veja se o agente identifica sozinho que deve usar a `gerar-ata`.
✏️ Copy-run — testar a skill
Objetivo: confirmar que a skill dispara sozinha por linguagem natural, sem chamar `/gerar-ata` na mão.
gera a ata dessa reunião: presentes joão, marcela e eu.
falamos do orçamento de , decidimos
adiar pra semana que vem, marcela fica de mandar a planilha
até sexta. Como verificar: a resposta deve vir já formatada nas 4 seções do tópico 4 — se vier como texto corrido, volte no corpo do `skill.md` e deixe as seções mais explícitas.
✓ Testada antes de usar de verdade
- ✓Você já sabe onde ela erra antes de depender dela numa reunião importante
✗ Direto pro uso real
- ✗Primeiro teste é numa ata que vai pro cliente — risco alto por economia de 2 minutos
⚠️ Erros comuns e checklist
Antes de considerar a skill pronta, passe pelos erros que mais aparecem em quem está construindo a primeira.
⚠️ Atenção
- Front matter mal formatado (esqueceu um `---`): a skill nem aparece pro agente.
- Description genérica demais: a skill nunca dispara sozinha por linguagem natural.
- Corpo sem exemplo: o agente entende o formato errado na primeira tentativa.
✅ Checklist de build
- ☐ Pasta criada em `~/.claude/skills/`
- ☐ Front matter com `name` e `description` específica
- ☐ Corpo com passo a passo numerado
- ☐ Testada com um caso real, sem chamar `/comando` na mão
Exercício: depois que a `gerar-ata` estiver funcionando, adapte-a pra um segundo caso de uso — por exemplo, "gerar resumo de call de vendas" — mudando só a description e as seções da saída. É o mesmo esqueleto, propósito diferente.
Checagem rápida: por que testar a skill com um caso de mentira antes de usar de verdade?