What subagents solve
Long sessions hit these inefficiencies:
- Search results and log dumps eat the main context’s token budget
- Self-review by the main agent is biased — it tends to agree with its own work
- Independent tasks run sequentially, wasting wall-clock time
Subagents are helper agents in their own context. Only the result returns to the main conversation, keeping context clean. They also run in parallel.
Define a subagent
~/.claude/agents/<agent-name>.md or agents/<agent-name>.md inside a plugin:
---
name: code-reviewer
description: |
Use after a logical chunk of code is written to review it against
the original plan and project coding standards.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. Given a recent change set, identify:
1. Bugs and logic errors
2. Security vulnerabilities
3. Deviations from project conventions
Report only high-confidence issues. Skip stylistic nitpicks.Frontmatter fields
| Field | Purpose |
|---|---|
name | Identifier used to invoke |
description | Auto-invocation conditions (same role as a Skill’s description) |
tools | Tools this agent may use (defaults to main’s set) |
model | sonnet, opus, haiku (defaults to main’s model) |
How to invoke
Auto-invocation
When the description matches the situation, the main agent calls the subagent automatically via the Agent tool.
Explicit
Use the code-reviewer agent to review src/auth/Parallel
Issue multiple Agent calls in one message and they run concurrently:
In parallel:
- code-reviewer on src/auth/
- security-auditor on dependency vulnerabilities
- test-coverage-analyzer on missing test areasYou get all three reports together.
When to use vs skip
| Good fit | Skip |
|---|---|
| Code reviews (independent perspective) | Next step in main work |
| Broad search/exploration | Needs user interaction |
| Security or perf audits | Needs shared progress |
| Concurrent multi-area analysis | Short, simple questions |
| Isolating long output from main context | Output drives main decisions immediately |
Writing a good description
Auto-invocation depends on description quality.
Good
description: |
Use after writing or modifying code in a logical chunk
(a feature, a bugfix, a refactor) to review the change against
the original plan and project coding standards. Reports
high-confidence issues only.Bad
description: Reviews code # too vague — won't trigger reliablyRestrict tools
The tools field limits what a subagent may use:
tools: Read, Grep, Glob # read-only — cannot modify codeReview and audit agents typically run safest as read-only.
Patterns
Pattern 1: protect main context
For long search results or logs, delegate to a subagent and only get the summary back.
Use the explore agent to find 'authentication' across src/ and report the locations and patterns in 200 chars.Pattern 2: independent review
Self-review introduces bias. Ask a subagent for an independent take.
Use the code-reviewer agent to independently assess if my recent migration is safe. Don't agree with my analysis — judge on its own.Pattern 3: parallel analysis
In parallel:
- agent-A on X
- agent-B on Y
- agent-C on ZNext steps
- Superpowers — bundles well-designed agents like code-reviewer
- Code Review, PR Review — review-focused agent collections
- Build a Skill — standardize subagent invocation via Skills