🎯 What we’ll build
Let’s create the skill gerar-ata: you paste into the chat the rough notes you took during a meeting — even if they're messy, abbreviated, and have incomplete sentences — and the agent returns formatted meeting minutes, with the date, participants, decisions, and next steps separated into sections. It's a small example of a purpose, but the build process is exactly the same one you’ll use for any larger skill.
Why this example and not a flashier one? Because it has clear input (the rough text), clear output (the formatted minutes), and rules you can test right away — the three ingredients of a first skill that teaches you well without drowning you in detail.
💡 Main Concept
- •Input: loose meeting notes pasted into the chat.
- •Output: formatted minutes with the date, attendees, decisions, and next steps.
- •The build process applies to any future skill of yours.
📁 The folder skeleton
Every skill starts with a folder. Inside it, at least one `skill.md` file. Since this is a personal skill,
which you want to use in any project (more on this choice in module 3.5), it will live in
~/.claude/skills/gerar-ata/ — `~` is a shortcut for "your user's home folder"
in the terminal (the text box where you give commands directly to the computer).
Caption: from the idea to the folder with the 4 pieces of `skill.md`, through the real test and the adjustment that closes the loop.
✏️ Copy-run—create the folder and file
Objective: asking Claude Code to create the skill’s folder structure.
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.How to verify: run ls ~/.claude/skills/ in the terminal and confirm that the folder containing the `skill.md` file appears.
🏷️ Writing the front matter
New here? Front matter it’s the metadata block at the top of `skill.md`, between two lines with three dashes (`---`). That’s where `name` (the skill’s name) and `description` (the phrase the agent compares with your request to decide whether to use that skill—covered in more depth in module 3.4) are stored. Without front matter, the agent doesn’t even know the skill exists.
skill.md — header
---
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".
---✓ Specific description
- ✓Says what the skill delivers
- ✓Says when to use it, with real user phrases
✗ Vague description
- ✗"Helps with meetings" — doesn’t say what or when
- ✗The agent may never trigger
📝 Writing the body
After the front matter comes the regular Markdown body: the step-by-step instructions the agent follows when the skill is triggered. Write as if you were guiding an attentive intern—brief, numbered, and without fluff.
Read the pasted notes
Identify the date (if it’s missing, ask), people mentioned, decisions made, and pending items.
Create the minutes in 4 fixed sections
Date and participants / Agenda / Decisions / Next steps with an owner.
Show the minutes and ask if anything is missing
Never invent a decision that wasn’t in the original text.
💡 Practical Tip
If the body is longer than 1–2 pages of very detailed instructions, that’s a sign to move some of it to a reference file (modules 3.1 and 3.2) instead of bloating the main `skill.md` file.
🧪 Test and adjust
A written skill isn’t a ready skill—it only proves its value when it’s actually triggered by a real case. Paste notes from a fictional meeting and see if the agent identifies on its own that it should use `gerar-ata`.
✏️ Copy-run—test the skill
Objective: confirm that the skill runs on its own from natural language, without manually calling `/gerar-ata`.
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. How to verify: the answer should already be formatted into the 4 sections from topic 4 — if it comes back as continuous prose, go back to the body of `skill.md` and make the sections more explicit.
✓ Tested before real use
- ✓You already know where it makes mistakes before you rely on it in an important meeting
✗ Straight to real-world use
- ✗First test is on meeting minutes going to the client — high risk for a 2-minute savings
⚠️ Common mistakes and checklist
Before considering the skill ready, review the mistakes that come up most often for people building their first one.
⚠️ Attention
- Poorly formatted front matter (forgot a `---`): the agent won't even see the skill.
- Description too generic: the skill is never triggered on its own by natural language.
- Body without an example: the agent gets the format wrong on the first try.
✅ Build checklist
- ☐ Folder created in `~/.claude/skills/`
- ☐ Front matter with a specific `name` and `description`
- ☐ Body with numbered step-by-step instructions
- ☐ Tested with a real case, without manually calling `/comando`
Exercise: once `gerar-ata` is working, adapt it for a second use case — for example, "generate sales call summary" — changing only the description and the output sections. Same skeleton, different purpose.
Quick check: Why test the skill with a fake case before using it for real?