Halfway through a debugging session, my main conversation with Claude Code was 60% full and most of it was junk: a full test-suite dump, three grep sweeps across the repo, and a stack trace I'd already read. None of it mattered anymore, but all of it was still sitting in the context window, crowding out the reasoning I actually needed. The model wasn't getting dumber. It was getting buried.
That is the problem sub-agents were built to solve, and the fix reframes how you work with an AI coding assistant. Instead of one generalist that reads everything and remembers all of it, you assemble a small team of specialists, each with its own context window, its own tool budget, and one job it's good at.
What a sub-agent actually is
A sub-agent is a specialized assistant that Claude Code can hand a task to. It runs in a separate context window with a custom system prompt and a specific set of tools, does its work independently, and returns only a summary to your main conversation. The verbose middle — the log files, the search results, the intermediate reasoning — never touches your primary context.
Use a sub-agent when a side task would flood your main conversation with output you won't reference again. The sub-agent does that work in its own window and hands back the conclusion, not the mess.
Mechanically, a sub-agent is just a Markdown file with YAML frontmatter. Here's a code reviewer scoped to read-only tools:
---
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 ensuring high standards of code quality
and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
The frontmatter is the contract; the Markdown body becomes the sub-agent's system prompt. Four fields carry most of the weight:
name — a unique, lowercase-hyphenated identifier.description — the single most important field. Claude reads it to decide when to delegate. Vague descriptions get ignored; specific ones with phrasing like "use proactively" or "use immediately after" get picked up on their own.tools — an allowlist. Omit it and the sub-agent inherits every tool; include it and you've drawn a hard boundary. A reviewer with only Read, Grep, Glob literally cannot edit your files.model — sonnet, opus, haiku, or inherit. Route cheap, high-volume work to a smaller model and save the expensive one for reasoning.
Where the files live
Location decides who can use a sub-agent:
| Path |
Scope |
Priority |
.claude/agents/ |
This project |
Higher |
~/.claude/agents/ |
All your projects |
Lower |
Project files win when names collide, which is exactly what you want — a repo-specific reviewer should override your generic personal one. And because project sub-agents are plain files in the tree, you check them into version control. Your test-runner, your migration-checker, your API-conventions reviewer travel with the codebase and improve as the whole team edits them.
You can scaffold one by hand, or run /agents and let Claude write the frontmatter and prompt for you from a plain-English description.
From one specialist to a team
A single sub-agent saves context. The real shift is composing several. Delegation happens two ways.
Automatic: you describe a task, and Claude matches it against every sub-agent's description and routes the work itself. This is why the description field earns its keep — it's the routing table.
Explicit: you name the agent when you want to be sure.
Use the test-runner subagent to run the suite and report only the
failing tests with their error messages.
From there, two patterns turn specialists into a team.
Chaining runs them in sequence, each handing its result to the next:
Use the code-reviewer subagent to find performance issues, then use
the optimizer subagent to fix them.
Parallel research fans out independent investigations at once:
Research the authentication, database, and API modules in parallel
using separate subagents.
Each explorer works in isolation and Claude synthesizes the findings. This is the highest-leverage move for a large codebase: three read-only agents comb three modules simultaneously, and your main context receives three summaries instead of three floods of source. The one caveat — every summary that comes back still costs context, so a swarm that each returns a detailed report can undo the savings. Keep the returns terse.
Designing agents that pull their weight
After building a handful, the rules that matter are unglamorous:
- One job each. A "backend helper" that reviews, tests, and refactors delegates poorly because Claude can't tell when to reach for it. Split it.
- Write the description for the router, not for yourself. State the trigger condition explicitly. This is what gets the agent invoked at the right moment.
- Scope tools tightly. Least privilege isn't just safety; a reviewer that can't write files can't "helpfully" rewrite your code mid-review.
- Check them in. A good sub-agent is shared infrastructure, not a personal snippet.
Sub-agents aren't always the answer. When a task needs tight back-and-forth, or several phases share the same context — plan, implement, test — keep it in the main conversation. A fresh sub-agent starts cold and spends time re-gathering what your main thread already knows. The dividing line is simple: delegate self-contained work that produces output you won't reread; keep iterative work where the context already lives.
The concrete takeaway: audit your next session for the moment your context fills with output you'll never look at again — a test run, a doc fetch, a log sweep. That exact task is your first sub-agent. Write ten lines of frontmatter, point it at read-only tools, commit it, and let the mess live somewhere your reasoning doesn't have to.
Sources: Claude Code — Create custom subagents