📋 A skill is your agent’s SOP
New here? POP it’s the abbreviation for “standard operating procedure”—the written step-by-step process a company uses to make sure a task is always done the same way, no matter who performs it. A skill it’s exactly that, but for your agent: a reusable text file that teaches, in detail, how to carry out a specific process—from “how to write a post in my company’s style” to “how to generate a financial report following these rules.”
The difference from what you’ve already seen in Track 2 is the trigger. The agent chooses an MCP tool (module 2.1)
on the spot, based on what’s available. It loads a skill when recognizes the task — whether because
you typed a explicit command (type /relatorio-financeiro),
either because your natural-language request matches the description the skill gives of itself.
No one needs to type a command—just describe what you want.
💡 Main Concept
Skill = reusable Markdown, loaded when the agent recognizes the task, triggered by a command or natural language.
- •A new employee doesn't have years of your experience—but they can consult the laminated manual on the desk.
- •The skill is that manual: written once, consulted every time the task comes up again.
🔍 Inside
You already have mental SOPs you’ve never written down: "when a client complains about a deadline, I first confirm the date, then offer two options." The skill makes you write that down once — and the agent follows that same process every time without missing a step.
📁 Inside the folder
Physically, a skill is a folder with the skill name.
Inside it, a required file called skill.md,
and two types of optional content: a folder references/
with longer documents, and a folder scripts/
with small programs the skill can run.
Caption: the only required file is skill.md at the top of the folder; references/ e scripts/ exist, but they’re only opened when the instructions say to — that’s the subject of module 3.2.
🏷️ The front matter: the skill’s label
New here? Front matter it’s
a metadata header at the top of a markdown file, bounded by three dashes (---) above and below.
Think of it as the label on the spine of a physical file folder: before you
open and read everything, you already know what it’s about just by looking at the label.
A skill’s front matter needs at least two fields: name (the
skill’s short name) and description (a
sentence saying what the skill does and when to use it). That’s all the agent reads all the time — the file’s body
is opened only when the skill is actually triggered. This is covered in more detail in module 3.2.
---
name: relatorio-financeiro
description: Gera o relatório financeiro mensal no padrão da empresa,
a partir de uma planilha exportada do sistema de vendas. Use quando
o usuário pedir "relatório financeiro", "fechamento do mês" ou
"resumo de vendas".
---
# Relatório financeiro mensal
## Passo a passo
1. Peça o caminho da planilha exportada se não foi informado.
2. Leia as colunas: data, valor, categoria.
3. Some por categoria e calcule o total do mês.
4. Gere o arquivo `relatorio-<mês>.md` seguindo o modelo em
`references/modelo-relatorio.md`.
5. Mostre o resumo em texto antes de salvar o arquivo.💡 Practical Tip
Write the description thinking about how YOU would ask for the task out loud, not in technical terms. That's the phrase the agent compares with your request to decide whether that skill applies. Module 3.4 is all about this.
📝 The body: the actual step-by-step
After the front matter, the rest of the skill.md it’s
regular markdown—the same text format as CLAUDE.md (module 0.4). This is where the process itself lives: the
numbered steps, the rules to follow, the examples, the warnings about what no do. Think of this as the
inside of the laminated manual: the label on the cover told you the subject, and now the inside pages teach
the full procedure.
✓ Well-done anatomy
- ✓Numbered steps, one per line, in execution order
- ✓Long details (code tables, extensive examples) pushed into
references/ - ✓Explicitly says when NOT to use the skill
✗ Poorly done anatomy
- ✗A block of text with no clear steps
- ✗Paste everything into the
skill.md— including the huge table that is only used once every ten runs - ✗Assumes the agent “will guess” when something isn’t written down
🔍 Inside
There’s no strict size limit, but the best practice is to keep the body short — about a paragraph of context and a list of steps, usually no longer than a page. If the subject needs much more detail, that’s a sign that part of it should become a file in references/, and keep the main body from getting bloated.
📚 References and scripts: the appendices
The folder references/ stores
longer documents — a category table, a glossary of internal terms, an extensive example —
that the agent opens only if the instructions explicitly say to (“if you need detail X, read file Y”).
It’s the technical appendix of the manual: it exists, it’s there, but nobody keeps it in mind all the time.
The folder scripts/ stores
small programs — a Python script that calculates a total, a shell script that renames files in batches —
that the skill can run instead of asking the agent to reinvent all that logic from scratch every time. It runs faster
and produces the same result every time because it’s deterministic code, not a new model decision on each run.
🎯 Main Concept
- •
references/= on-demand knowledge (the agent reads text) - •
scripts/= on-demand action (the agent runs code) - •Neither affects day-to-day work — they only come into play when called
💡 Practical Tip
Practical rule for deciding where something goes: if you reread that section every time you run the skill, it belongs in the body of the skill.md. If you only look it up now and then ("what's the code for category X again?"), it goes in references/.
⏱️ What happens when the skill is called
Putting it all together: when you ask for something in natural language or type the command, the agent goes through a short sequence of decisions until the skill becomes an action. See the timeline of a real call.
You ask: "wrap up this month’s financial report"
Regular sentence, no special command.
The agent compares your phrase with the description of each installed skill
Recognize how it matches the skill’s description relatorio-financeiro.
Loads the entire body of that skill’s skill.md
Now read the full step-by-step guide—not just the label.
Follows the steps; opens references/ or runs scripts/ only if the step says to
In this example: read the report template at references/ in step 4.
⚠️ Attention
If two skills have descriptions that are too similar, the agent may choose the wrong one—or hesitate. Module 3.4 shows you how to write triggers that don’t conflict.
Quick check (optional): What is the only required file inside a skill’s folder?