What’s a subagent?
A specialized Claude instance with its own context window, custom system prompt, and specific tool access — useful for tasks like code review, testing, or research that would otherwise clutter your main conversation.
Steps to create one
Option A — Ask Claude to write it for you (recommended)
- In a Claude Code session, describe the subagent you want, e.g.:
“Create a personal code-improver subagent in ~/.claude/agents/ that scans files and suggests improvements for readability, performance, and best practices. Make it read-only and have it use Sonnet.” - Claude will generate the Markdown file with the right frontmatter (name, description, tools, model) and system prompt.
- Open the file it created and tweak anything you’d like.
Note: as of Claude Code v2.1.198+, the old
/agentsinteractive wizard was removed. Running/agentsnow just reminds you to ask Claude directly or edit the files yourself — but the file format and locations are unchanged.
Option B — Write the file manually
- Create a Markdown file in one of these locations:
.claude/agents/your-agent-name.md→ project-level (shared with your team via the repo)~/.claude/agents/your-agent-name.md→ personal, available across all your projects
- Add YAML frontmatter + a system prompt body. Example:
markdown
---name: code-reviewerdescription: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.tools: Read, Grep, Glob, Bashmodel: sonnetYou are a senior code reviewer. When invoked: Run git diff to identify modified files. Focus review on changed code paths. List security issues, likely false positives, and suggested fixes. Provide a short, prioritized action list.
- Restart your Claude Code session — subagent files are loaded only at startup, so edits on disk won’t take effect until you restart. (Agents created via asking Claude in a live session take effect immediately.)
Key frontmatter fields
| Field | Purpose |
|---|---|
name | Unique identifier |
description | This is what triggers delegation — Claude matches tasks against it, so write it as a clear condition for use (e.g. “Use PROACTIVELY after writing code”) |
tools | Restrict which tools the subagent can access (e.g. Read, Grep, Glob for a read-only reviewer) |
model | sonnet, opus, haiku, or inherit (uses parent’s model) |
Using it
- Let Claude auto-delegate based on the
descriptionmatching your request, or - Invoke explicitly:
claude -p "Use the code-reviewer subagent to review payment.py"
Claude Code also ships with built-in subagents (Explore, Plan, general-purpose) that it uses automatically without you needing to configure anything.
Conclusion
Subagents are one of the most practical upgrades you can make to your Claude Code workflow. By delegating token-heavy, repetitive, or specialized tasks — like code review, testing, or codebase exploration — to a dedicated subagent, you keep your main conversation focused and your context window clean.
Getting started is simple: describe what you want to Claude and let it generate the subagent for you, or hand-write a Markdown file with the right YAML frontmatter in .claude/agents/ or ~/.claude/agents/. From there, it’s just a matter of refining the description field so Claude knows exactly when to delegate, and restricting tools and model choices to match the task at hand.
Start small — one or two subagents for your most repetitive tasks — and expand as you find more workflows worth isolating. Once you experience how much cleaner and faster your sessions become, it’s hard to go back to a single generalist agent handling everything.
Leave a Reply