🏷️ Step 1 — Name and trigger
New here? O front matter is the metadata block at the top of `skill.md`, between two `---` lines, in the `key: value` format. That's where the
name (the skill identifier) and the description
(the text the agent reads to decide whether to use this skill). Step 1 is to choose both carefully.
Think of a cake recipe: the title on the cover of the notebook (“Grandma’s carrot cake”) tells you when you’re going to
open that page. The `name` is that title—short, with no spaces, like relatorio-mensal-cliente.
A description is the back-cover summary: when to use it and what situations it fits. It's covered in full in module 3.4 — here, what matters is knowing it exists and lives in step 1.
💡 Main Concept
Step 1 isn’t bureaucracy — it’s what helps the agent FIND the right skill among 20 others.
- •
name: a short, unambiguous technical identifier that doesn't conflict with another skill. - •
description: a sentence that describes WHEN to use it, not just what it is.
✨ Practical Tip
Test your name and description by asking the agent in a new session, “What skills do you have installed, and when would you use each one?”—if its answer about your skill doesn’t match your intent, step 1 needs adjustment.
🎯 Step 2 — Goal in one sentence
Right after the front matter, the skill needs a clear sentence explaining what it DELIVERS. Not “helps with reports” (vague), but “generates a monthly report PDF from the client’s sales spreadsheet, ready to send by email” (concrete, with the final result named). It’s the equivalent of a photo of the finished cake on the first page of the recipe—you know exactly where you’ll end up before reading the step-by-step instructions.
Ambiguity is costly here: if the goal can be interpreted in two ways, the agent will choose one at the wrong time. “Organize my files” could mean renaming them, moving them into folders by date, or deleting duplicates—three very different things. Write the goal as if it were the last sentence someone reads before approving.
✓ Clear goal
- ✓"Generates the monthly PDF report, with a sales-by-region chart, from the `vendas.xlsx` spreadsheet."
- ✓Specify the input, output, and final format — zero room for interpretation.
✗ Vague objective
- ✗"Helps organize the company’s reports."
- ✗Doesn’t specify the output format or where the data comes from — the agent guesses.
🪜 Step 3 — Verifiable step-by-step instructions
Here’s where the body of the skill lives: the numbered sequence of actions the agent follows. Each item needs to be verifiable — you can check whether it happened or not. "1. Open the spreadsheet `vendas.xlsx`. 2. Sum the 'total' column by region. 3. Generate a bar chart. 4. Export it as a PDF." Each numbered item is a pilot checklist: before takeoff, it checks each item one by one, in order, without skipping any.
Caption: the 6 steps form a pipeline that closes in a loop — after step 6 (improvement), the skill returns to step 1 on the next run, already a little better.
✨ Practical Tip
Write each step as a sentence that starts with an action verb ("Open," "Add," "Generate")—if you can’t write a concrete verb, that step is probably too vague and will lead to an arbitrary decision by the agent.
📚 Step 4 — References without bloating the main file
Not everything needs to go in `skill.md`. Long details — error code tables, extensive examples,
document templates — belong in separate files inside the skill folder (usually a subfolder
references/), and `skill.md` only POINTS to them when needed.
This is the three-level loading from module 3.2 in practice: the agent only reads the reference if the
situation calls for it, so the main `skill.md` stays lean and inexpensive to load each time.
Put only what’s always needed in `skill.md`
The 6 steps and the essentials go in the main file — read every time it’s invoked.
Move the rest to `references/arquivo.md`
Rare examples, large tables, edge cases—loaded only on demand.
Point to it with one line in the relevant step
"If the client is X, see `references/regras-cliente-x.md` before generating."
🚫 Step 5 — Rules and "don'ts"
The most skipped step — and the one that causes the most headaches when it’s missing. Rules are explicit constraints: what the agent must NEVER do on its own, even if it seems like the fastest way. “Don’t send the email without me reviewing it first.” “Don’t overwrite the original file — always create a copy.” “Don’t delete spreadsheet rows; just mark them as processed.” Without these safeguards, an efficient agent without context will take the dangerous shortcut because it technically works — it’s just not what you wanted.
✓ Skill with all 6 steps completed
- ✓Has explicit "Rules": "don’t delete, only archive."
- ✓Agent hesitates and asks before taking an irreversible action.
- ✓Recurring errors are recorded and become a new rule (step 6).
✗ Skill that skips "rules"
- ✗Only has “do this, do that”—no explicit limits.
- ✗Agent deletes the original file thinking it's "cleaner."
- ✗The same error repeats with every run because nothing was written to prevent it.
⚠️ Attention
A vague rule offers no protection. “Be careful with sensitive data” doesn’t prevent anything — “never write a customer’s CPF or email in a log or commit” does. Be as specific as someone writing a pilot checklist, not a generic footer warning.
🔁 Step 6 — The improvement cycle
A skill isn't perfect from the start — just like no one gets a cake recipe right on the first try. Step 6 is the habit of reviewing it after using it a few times: what went wrong? Did the agent hesitate at any point? Did it do something you didn't want? Each answer becomes a new line in steps 3 or 5 (another step or another rule). That's how a skill goes from "works sometimes" to "reliable every time."
Run 1: the skill runs, but the agent asks too many questions—explicit decisions are missing from the steps.
Runs 2–3: you add rules after seeing the agent take a dangerous shortcut once.
Runs 4–9: rare cases become separate references — the main `skill.md` stays concise.
Starting with the 10th: the skill runs without surprises—it’s the point where it truly becomes reliable (covered in depth in 3.7).
Example of skill.md with the 6 elements marked
---
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).Copy-run—objective
Ask Claude Code to scaffold a new `skill.md` with the 6 steps already marked, ready for you to fill in.
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.How to verify: open the generated file and check that all 6 sections are there, in order, and that the description mentions real situations (not jargon) that would trigger the skill.
Quick check (optional): Why is step 5 (rules) often the most important when it’s missing?