Every time the conductor invokes a subagent, it is reading a file .md.
This file has two required zones: o
frontmatter (among the three traits ---)
e o body (everything else comes later). The first zone configures the agent — defines its name,
trigger, tools, and model. The second zone is the brain — defines who it is and what it does.
Together, these two parts make up the complete subagent.
↑ The subagent equation: frontmatter (config) + body (brain) = complete agent.
Detailed content
📄 The .md file is the subagent
If you’ve already worked with skills in Claude Code, you've already seen the structure: a Markdown file with frontmatter at the top. A subagent is exactly that — a .md with
a configuration frontmatter and an instruction body. It isn’t a binary, compiled code, or a plugin.
It’s a text file that any editor can open.
🔑 Why this matters
When the file is plain text, you get three things for free:
- •Readability — you read, understand, and edit it without a special tool.
- •Version control — goes into Git with the project. Diff works.
- •Portability — copy the folder
.claude/agents/to another project, and the agent goes with it.
📋 Skill (.claude/skills/)
Invoked with /skill-name · same model and tools as the chat · same context window.
🤖 Subagent (.claude/agents/)
Triggered by the description · separate window · distinct model and tools · returns only the report.
A Markdown file with frontmatter + body. The analogy with skill.md is intentional — same structure, different purpose.
Demystify the subagent. There’s nothing hidden: everything the orchestrator knows about the agent is in this file.
.md file · YAML frontmatter · Markdown body · versionable in git · portable across projects.
⚙️ Frontmatter (config) × body (brain)
The two zones have completely different responsibilities. The frontmatter is read by Claude Code to decide if it triggers the agent and how it will run. The body is the prompt sent to the model when it is invoked—it is literally that agent's "system." Confusing the two zones is the most common mistake when creating your first subagent.
⚙️ Frontmatter — what it does
- ✓Defines the agent identifier (
name) - ✓Describes when the orchestrator should use it (
description) - ✓List the allowed tools (
tools) - ✓Choose the model that will run (
model)
🧠 Body — what it does
- ✓Defines the agent's role (“You are a...”)
- ✓Describes the execution steps
- ✓Specify the output format
- ✓List what the agent must NOT do
🔑 The 4 key frontmatter fields
The frontmatter supports many fields, but four are the ones you’ll write in every subagent.
The others — color, memory,
disallowed-tools — they’re optional and covered in Track 2.
For now, master these four.
name — identifier
Lowercase + hyphens, no spaces. Appears in logs and FleetView. Use descriptive names: code-reviewer > cr.
description — trigger
The conductor reads this field to decide when trigger the agent. Vague description = agent never triggered. Track 2 is entirely dedicated to writing good descriptions.
tools — permissions
Least privilege principle: reader agent → Read, Grep, Glob. Editor agent → add Edit, Write. Don't omit it — without declaring it, it inherits everything from the maestro.
model — who executes
Mechanical → haiku. Analysis → sonnet. Strategic reasoning → opus. Making an intentional choice here saves cost and time. Track 3 goes deeper.
💡 All available fields
In addition to the four above, the frontmatter accepts: color (color in FleetView), memory (project/user/local/none), disallowed-tools (explicit blocking) and advanced MCP fields. The official documentation lists them all — link in topic 6 of this module.
🧠 The body: the brain’s four sections
The body is free-form Markdown — you can write whatever you want. But a well-formed body almost always has four parts. Think of them as sections in a briefing for a new employee: who you are, what to do, what to deliver e what never to do.
Role (Role)
The first line of the body. Defines the agent’s identity.
focused on security.
Steps (Steps)
What to do when activated, step by step.
1. Run git diff.
2. Read changed files.
3. Look for bugs.
Output (Output)
Format and content of what goes back to the orchestrator.
issues. Include file path
and line number.
Don't do (Limits)
Explicit boundaries — what the agent doesn't do.
From not open new files
beyond the diff.
✓ Well-formed body
- ✓Starts with "You are a..." — clear role
- ✓Unambiguous, numbered steps
- ✓Explicit output instruction (bullet, JSON, prose)
- ✓At least one “Do not...” to limit scope
✗ Weak body
- ✗No role—the model improvises its identity
- ✗Vague steps: "analyze the code"
- ✗No output instruction—the conductor doesn’t know what to expect
- ✗No limits—the agent edits when it should only read
📁 Where it lives: .claude/agents — the bridge to Track 2
Claude Code looks for subagents in .claude/agents/ in the project root.
It’s a hidden folder, just like .claude/skills/ that you already know.
Any .md Saved there, it’s automatically loaded as an available subagent—
no restart, no registration command.
seu-projeto/
├── .claude/
│ ├── agents/ # subagentes do projeto
│ │ ├── code-reviewer.md # ← aqui!
│ │ ├── test-writer.md
│ │ └── doc-writer.md
│ ├── skills/ # skills (diferente!)
│ └── CLAUDE.md # instruções do projeto
└── src/
└── …🗂️ Project — .claude/agents/
Only in this project · goes in git · shared with the team.
🌐 Global — ~/.claude/agents/
All projects · user’s home · personal agents.
🔭 Bridge to Track 2: In Track 2, you creates these files — complete frontmatter, actual body, and the command /agents to manage the catalog.
📚 Official documentation — all fields
The frontmatter supports more fields beyond the four essentials. The reference below covers the most commonly used ones.
📖 Frontmatter fields — quick reference
| Field | Required? | What it’s for |
|---|---|---|
| name | ✓ yes | Unique identifier—lowercase and hyphenated |
| description | ✓ yes | Trigger — when the orchestrator invokes this agent |
| tools | recommended | Allowed tools (comma-separated list) |
| model | recommended | Claude model that executes (haiku / sonnet / opus) |
| color | optional | Badge color in FleetView |
| memory | optional | Memory access: project / user / local / none |
| disallowed-tools | optional | Explicitly blocks specific tools |
Complete documentation: use /help agents in Claude Code (offline) or docs.anthropic.com/claude/code/agents. Advanced fields such as memory e disallowed-tools unlock extra behaviors covered in Track 3+.
Fully annotated .md example
Read this doc-writer.md with attention to the notes in comments.
Each line is labeled with the section it belongs to and the reason it’s there.
--- ← delimitador de abertura do frontmatter
name: doc-writer
↑ identificador — minúsculas, hífens, sem acento
description: Escreve documentação técnica e READMEs
a partir de código existente. Use quando o usuário
pedir para documentar um módulo, função ou projeto.
↑ gatilho — 3 frases: o que faz, quando usar, sinal
tools: Read, Glob, Write
↑ menor privilégio — lê código, escreve .md, sem Bash
model: claude-sonnet-4-5
↑ sonnet: boa escrita, custo razoável. Haiku bastaria?
Não — qualidade de prosa importa aqui.
--- ← delimitador de fechamento do frontmatter
# corpo (tudo aqui é o prompt enviado ao modelo)
You are a technical documentation writer.
↑ papel — identidade do agente (primeira coisa!)
When invoked:
1. Read the files listed in the task.
2. Identify the public interface (exports, classes, functions).
3. Write a clear README.md at the module root.
↑ passos — numerados, ação concreta em cada um
Output: a single README.md file with:
- One-sentence summary
- Installation (if applicable)
- Usage examples in code blocks
- API reference table
↑ saída — formato explícito; o maestro sabe o que esperar
Do not invent behavior that isn't in the source code.
Do not modify source files — only create/update .md files.
↑ limites — dois "do not" que previnem alucinação e danoReady-made prompts (copy and paste)
Three prompts to explore the anatomy of a subagent you already have—or inspect what the orchestrator knows.
Abra o arquivo .claude/agents/code-reviewer.md e
me explique cada campo do frontmatter — o que faz,
por que está com esse valor e o que mudaria se eu
trocasse. Depois leia o corpo e identifique o papel,
os passos, a saída esperada e os limites.Liste todos os subagentes disponíveis em
.claude/agents/ e para cada um me mostre:
- o campo name e description
- as tools permitidas
- o modelo configurado
Formato: tabela markdown.Leia o arquivo .claude/agents/meu-agente.md.
O maestro nunca aciona este agente. Analise a
description: ela é específica o suficiente?
Tem as palavras-gatilho certas? Sugira 3 versões
melhoradas da description, do mais genérico
ao mais específico.Exercise — Label the parts
Below is a file .md of a subagent with 8 numbered lines.
For each line, identify: (a) which zone it is in (frontmatter or body), (b) which field or body section it represents.
✅ Criteria — you got it right if, for each line, you said:
- →Area: frontmatter (L1–L6) or body (L7–L8).
- →Field/section: delimiter, name, description, tools, model, role, or steps.
- →Impact: what breaks if this line disappears.
Bonus: which tool in L4 is the riskiest, and why Bash requires care.
Answer key
✅ Module summary
Next — Track 2:
Track 1 complete. In Track 2, you creates in practice: complete frontmatter (all fields), the description as a trigger, tools and permissions, and the command /agents to manage your catalog.