The Config File: Frontmatter and System Prompt
Anatomy of a Subagent File
A subagent is a Markdown file with two parts: YAML frontmatter (the configuration) and a Markdown body (the system prompt). It's typically saved to .claude/agents/your-agent-name.md. Only two fields are required — name and description — but several optional fields give you fine control.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.The Core Fields
| Field | Required | What it does |
|---|---|---|
| name | Yes | Unique identifier (lowercase + hyphens). How you reference it: '@agent-name' or by asking Claude. |
| description | Yes | Controls WHEN Claude delegates — and shapes the task prompt. Single line (use \n for breaks); can include example conversations. |
| tools | No | Which tools the subagent can use. Omit to inherit ALL tools. |
| model | No | sonnet, opus, haiku, a full model ID, or inherit. Defaults to inherit. |
| color | No | UI color to identify the subagent: red/blue/green/yellow/purple/orange/pink/cyan. |
The fields you'll touch most. name + description are mandatory; the rest are optional refinements.
The body IS the system prompt
Everything below the closing '---' is the subagent's system prompt — its instructions. A well-written system prompt is the difference between a useful subagent and one that misses the point. Be specific about what to look for and how to structure output. Subagents receive only this prompt (plus basic environment details), not Claude Code's full default system prompt.
Beyond the Basics: Powerful Optional Fields
The frontmatter supports more than the core five. You won't need these every time, but knowing they exist unlocks advanced subagents:
- •disallowedTools — a denylist; inherit everything EXCEPT these (applied before 'tools').
- •permissionMode — default, acceptEdits, plan, dontAsk, bypassPermissions (use the last with caution).
- •skills — preload full skill content into the subagent at startup.
- •mcpServers — give the subagent MCP servers (even ones the main conversation lacks).
- •memory — user/project/local: a persistent directory so the subagent learns across sessions.
- •maxTurns, effort, background, isolation (worktree), hooks, initialPrompt — finer execution control.
isolation: worktree
Set isolation: worktree to run the subagent in a temporary git worktree — an isolated copy of the repo. Its edits don't touch your working tree, and the worktree is auto-cleaned if it makes no changes. Useful for risky or parallel modification tasks.
Proactive Delegation and Examples
Two description techniques dramatically improve reliability. First, include 'use proactively' (or 'use immediately after...') to get Claude to delegate without being asked. Second, embed concrete example scenarios in the description — the more specific, the better Claude's matching.
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for
quality, security, and maintainability. Use immediately after writing
or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
...Next
You can read and write a subagent file. But where you put it changes who can use it — next we cover scope and precedence across project, user, managed, and plugin locations.
Key Takeaways
- ✓A subagent is a Markdown file: YAML frontmatter (config) + a Markdown body (the system prompt), typically at .claude/agents/name.md.
- ✓Only name and description are required; tools, model, and color are the common optional fields.
- ✓name = unique lowercase-hyphen id; description = controls when Claude delegates AND shapes the task prompt (single line, \n for breaks).
- ✓The body below the closing '---' is the system prompt — subagents get only this, not Claude Code's full default prompt.
- ✓Advanced frontmatter includes disallowedTools, permissionMode, skills, mcpServers, memory, maxTurns, effort, background, isolation (worktree), and hooks.
- ✓Add 'use proactively' / 'use immediately after...' and concrete example scenarios to the description to drive reliable automatic delegation.
Check Your Understanding
Test what you learned in this lesson.
Q1.Which two frontmatter fields are required in a subagent file?
Q2.In a subagent Markdown file, what is the content below the closing '---'?
Q3.What does omitting the 'tools' field do?
Q4.How do you make Claude delegate to a subagent automatically, without being asked?
Practice This Lesson