A subagent is a markdown file
Custom subagents live in .claude/agents/ (project, shared with the team) or ~/.claude/agents/ (personal). Each file has YAML frontmatter plus a markdown body, and the body becomes the subagent's system prompt.
---
name: code-reviewer
description: Reviews recent code changes for correctness bugs and risky patterns. Use proactively after any significant edit, or when the user asks for a review.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. Review only the current diff (`git diff main...HEAD`).
Look for, in priority order:
1. Correctness bugs: wrong logic, missing awaits, off-by-one, null handling
2. Security issues: injection, auth gaps, secrets in code
3. Missing tests for new behavior
Do NOT comment on style or naming.
Report format:
- One finding per bullet: `file:line`, the problem, and a concrete fix
- End with "VERDICT: ship" or "VERDICT: fix first"
- If you find nothing, say so plainly. Don't invent issues.The easiest way to create one? Ask Claude: "create a code-reviewer subagent in .claude/agents that…". Then edit the file yourself.
Frontmatter you'll use
| Field | Purpose |
|---|---|
name (required) | Unique identifier |
description (required) | When Claude should delegate. Add "use proactively" to encourage it. |
tools | Allowed tools. Omit it to inherit everything. |
disallowedTools | Tools to remove |
model | sonnet, opus, haiku, a full model ID, or inherit |
skills | Skills whose full content is preloaded into the subagent |
permissionMode | The subagent's permission mode |
maxTurns | Cap on how many turns it can take |
memory | Give it a persistent memory folder (project is recommended) |
isolation: worktree | Run it in its own git worktree |
A read-only helper with tools: Read, Grep, Glob and model: haiku is fast and inexpensive, which makes it perfect for lookups and summaries.
Where to save it
| Location | Scope |
|---|---|
.claude/agents/ | This project. Commit it so the team shares it. |
~/.claude/agents/ | You, across every project |
Plugin agents/ folder | Anyone who installs the plugin |
--agents '<json>' flag | Just this session |
If two definitions share a name, the project one beats the user one.
Test it
- ⋮⋮Create .claude/agents/code-reviewer.md with name, description and tools
- ⋮⋮Write a focused system prompt with a clear report format
- ⋮⋮Make a small change with a deliberate bug
- ⋮⋮Ask "review my changes" and confirm Claude delegates to code-reviewer
- ⋮⋮Tighten the description or prompt based on what happened
What do you type to guarantee the code-reviewer subagent handles a request? (Just the mention.)
Check your understanding
What becomes a subagent's system prompt?
Which two frontmatter fields are required?
What happens if you omit tools?
Where should a team-shared subagent live?