Build Claude Subagents Better Than 99% of People

From “what is this” to running your own fleet. What a subagent is, when to reach for one, how to write a great one, and how to save money doing it. Read top to bottom once, then keep it as a reference.

1 · The 30-Second Version

A subagent is a second Claude that your main Claude can hand a job to.

It runs in its own separate window, does the messy work (reading 40 files, searching the whole codebase, digging through logs), then hands back a short summary. All the noise stays in its window. Your main chat only sees the clean answer.

That is the whole idea. Everything else in this guide is detail on top of that one sentence. Three things to lock in before we go deep:

1. Subagents save your context. The main chat stays clean because the grunt work happens somewhere else.
2. There are built-in ones and ones you build yourself. Claude ships with a few. You can write your own as little files.
3. You can specialize them. Each one can have its own job, its own tools, and its own (cheaper) model.

2 · The Mental Model (Read This Twice)

Picture your main Claude session as you, the general contractor on a job site.

You do not personally read every spec sheet, count every nail, and inspect every weld. If you did, your head would be so full of detail you would lose track of the actual build. Instead you send specialists off: “Go inspect the foundation and report back.” They go do the dirty, detailed work. They come back and say “Foundation’s good, one crack on the north wall, here’s the photo.” You never had to hold all that detail in your own head.

That is exactly what a subagent is. A specialist you send off so your own head (the context window) stays clear.

Why this matters: the context window problem

Claude has a limited memory for any single conversation. Every file it reads, every search result, every log line gets added to that memory and stays there for the rest of the chat. Do enough heavy work and the window fills up. When it fills up, Claude gets slower, more expensive, and starts forgetting things from earlier.

Heavy tasks are the worst offenders:

• Searching 200 files for one pattern dumps dozens of file contents into memory.
• Running a test suite dumps hundreds of lines of output.
• Researching a problem dumps pages of documentation.

A subagent does all of that in its own memory. When it finishes, only the final summary comes back to your main chat. The 200 file reads, the test output, the research pages all stay behind in the subagent’s window and disappear when it is done.

3 · The Two Kinds of Subagent

Kind 1 · Built-in: native subagents

These ship with Claude Code. You do not create them. Claude reaches for them automatically when a task fits. You’ll often see it say “Exploring…” without you asking.

You get value on day one without building anything. The built-ins are already working for you. Building your own is the next level, not the entry fee.

Kind 2 · Custom: the ones you build

These are the ones you write. They live as little Markdown files in a folder. They are how you create a permanent “code reviewer,” a “researcher,” a “test runner,” whatever recurring specialist you need.

The rest of this guide is mostly about these.

The three built-ins that do real work

There are also small helper agents Claude uses behind the scenes (one that sets up your status line, one that answers questions about Claude Code itself). You will rarely think about those.

4 · What a custom subagent looks like

A custom subagent is just one Markdown file with two parts: a frontmatter block at the top (settings, in YAML between --- lines) and a body below it (plain-English instructions that become the subagent’s whole personality and job).

---
name: code-reviewer
description: Expert code review specialist. Use proactively after writing or modifying code. Also triggers on "review my changes" or "check this PR".
tools: Read, Grep, Glob, Bash
model: sonnet
---

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 without asking for clarification

Review checklist:
- Code clarity and readability
- Proper error handling
- No exposed secrets or API keys
- Input validation present
- Adequate test coverage

Provide feedback in three tiers:
- Critical (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific file paths and line references.

That is it. That file IS the subagent. Drop it in the right folder and Claude can now use it.

Where these files live: project-level vs global-level

This is the part beginners get wrong most often, so go slow here. It comes down to one choice: where you save the file. That single choice decides two separate things: where you can use the agent (which projects it shows up in) and who else gets it (just you, or your whole team).

Option A · Project-level: .claude/agents/ in a repo

Where you can use it: ONLY inside that project. Open a different project and it’s gone. It’s bolted to this one repo.

Who else gets it: Your whole team. It gets committed to git, so a teammate who clones or pulls gets the agent automatically, no install.

Best for: agents that only make sense for this codebase: a “run our test suite” agent, a reviewer that knows your conventions, a deploy helper.

Option B · Global / user-level: ~/.claude/agents/ in home

Where you can use it: Every project on your machine. It follows you everywhere.

Who else gets it: Nobody. Just you. It’s not part of any repo. It’s your private toolkit. A teammate only gets it if you hand them the file.

Best for: your personal favorites: a general researcher, an “explain this code” helper, agents you reach for no matter what you’re working on.

When the same name exists in both

If a project-level agent and a global agent share the same name, the project one wins inside that project. This is on purpose. It lets a project override your personal default with a project-specific version. Everywhere else, your global one still applies.

Two smaller notes

• You can organize agents into subfolders (like .claude/agents/review/security.md). The path changes nothing. Only the unique name field matters.
• There are a couple more advanced scopes (plugins can ship agents; enterprises can push org-wide managed ones). For 99% of use, project- and global-level are the only two you need.

5 · How Claude Decides to Use One

You almost never call a subagent like a function. Claude picks them for you. Four ways it happens, from most hands-off to most deliberate.

1. Automatic delegation (the default)

Claude reads the description field of every available subagent and routes to the matching one. This is why the description is the single most important line in the whole file. It is not a label. It is the trigger rule.

• Weak: “Security expert” (Claude has no idea when to use this)
• Strong: “Reviews code for security vulnerabilities. Use proactively after writing auth or data-handling code. Triggers on ‘check this for security issues’.”

2. Proactive invocation

Put the literal phrase “use proactively” in the description and Claude will reach for the agent without you asking. For example, a code reviewer that fires automatically right after you change code.

3. Explicit, by name

Just ask in plain English: “Use the test-runner subagent to fix the failing tests.” Or guarantee a specific one runs by @-mentioning it: @agent-code-reviewer check the auth changes. The @-mention is the “I definitely want THIS one” button.

4. As the whole session’s default

You can launch Claude so a subagent’s personality runs the entire session: claude --agent code-reviewer. Most beginners never need this, but it exists.

6 · The Settings (Frontmatter Fields)

You only need two fields to have a working subagent. Everything else is optional power.

The two required fields

The two you’ll use constantly

The advanced fields (newer versions, nice to know)

Start with the four. Reach for these later.

7 · Tools (and Why You Restrict Them)

If you don’t list any tools, your subagent inherits everything the main session has: reading, writing, running commands, web access, your connected services, all of it. That is usually too much.

Restricting tools is free, physical enforcement. A code reviewer that only has Read, Grep, Glob literally cannot modify your code, no matter what goes wrong. You are not trusting it to behave. You made misbehaving impossible.

Two ways to control it: tools: is an allowlist (only these, nothing else); disallowedTools: is a denylist (everything except these). For a reviewer, an allowlist is cleanest. For “give it the works but never let it write,” a disallowedTools: Write, Edit denylist is faster.

8 · Saving Money with Subagents

One of the biggest wins, and one of the easiest places to shoot yourself in the foot.

Lever 1: Run cheap agents on cheap models

Every subagent can run on a different model. This is the main cost dial.

Prices are approximate and change. Treat them as ratios, not gospel.

The pattern that wins: a smart model running the show, cheap models doing the legwork. Anthropic’s own multi-agent research system used an Opus “lead” with Sonnet “workers” and beat a single Opus by a wide margin on hard research tasks. The model mix beats raw spend.

• Set your codebase explorer and doc writer to model: haiku. They don’t need deep reasoning.
• Keep reviewers and implementers on sonnet.
• Reserve opus for the security auditor and gnarly debugging.
• You can also set CLAUDE_CODE_SUBAGENT_MODEL to force a cheap model on all subagents at once (great for automated/CI runs).

Lever 2: Context offloading (the structural saving)

This is the saving you get just by using subagents at all. The subagent reads 50 files in its own window and hands back a 3-paragraph summary. You paid for those 50 file reads once, over there. They never enter your main chat, so you’re not re-paying to carry them in context for the rest of your session. On a long session, this is enormous.

The rule: if the job would read 10+ files or spit out noise you’ll never need again, a subagent saves money overall. If it’s a small, targeted change, do it inline and skip the overhead. Bonus lever: set maxTurns on any agent that might wander.

9 · When to use one

A quick test will tell you whether the task belongs in a subagent.

“Is this task about to dump a pile of stuff into my chat that I’ll never need to look at again?”

If yes, that’s a subagent. If no, it’s probably not. That’s the whole heuristic, and it traces straight back to Part 2: subagents exist to protect your main context. Almost every “should I use one” question is really this question in disguise.

Signals that say “use a subagent”

Use one · 1. It’s going to read a LOT of files.

Searching the whole codebase, scanning 15 files, crawling a directory. Each would land in your main context and sit there. The subagent absorbs it all and returns a summary. The most common trigger.

Use one · 2. It’ll spit out a wall of output you glance at once.

The test suite, a giant log, pages of web research, a noisy build. The raw output is throwaway. You want the verdict (“3 tests failed, all in auth”), not 400 lines of stack traces.

Use one · 3. You keep doing this exact task over and over.

Reviewing every PR, auditing every auth change, updating docs after each release. Package it once as a specialist and it’s permanent: no re-explaining, consistent standard.

Use one · 4. Several independent jobs, none needs another’s output.

The parallel test. Fire several at once: auth, database, API routes explored simultaneously, then synthesize. If the pieces ARE ordered (step 2 needs step 1), it’s not parallel, so stay inline.

Use one · 5. You want a second opinion not biased by how you built it.

A fresh subagent never saw your reasoning, so it judges the result on its own terms. Your main chat is emotionally invested in the code it just wrote. The fresh context is the feature.

Use one · 6. You do NOT want it able to change anything.

A subagent with only Read, Grep, Glob physically cannot edit or delete. For an auditor turned loose on a repo, that lockdown is enforced, not a suggestion.

Use one · 7. Your context is almost full but you’re not done.

Offload the next heavy chunk so you keep going without compacting or losing the thread of your main session.

Remember · The fast rule of thumb

10+ files, or output you’ll never re-read = subagent. Under that bar, stay inline.

Signals that say “do NOT use one”

Stay inline · 1. It’s small and quick.

A subagent has real startup cost: a blank context it must re-gather. If the task takes 30 seconds inline, you paid setup overhead for nothing. The most common misuse, and why people call subagents “slow.”

Stay inline · 2. You’re in a tight back-and-forth.

Step 2 depends on the full detail of step 1, step 3 on step 2. Subagents hand back a summary and run start-to-finish without checking in. Iterative work belongs inline where you steer turn by turn.

Stay inline · 3. It needs everything you’ve talked about.

A subagent starts blank. If the job needs the last 20 messages, either re-explain it in the task (clunky) or use a fork, a subagent that DOES inherit the full conversation (Part 15).

Stay inline · 4. It’ll need to ask you a question partway.

Subagents can’t stop to ask anything; background ones auto-deny anything that would prompt you. If the task is ambiguous, clarify it BEFORE you delegate.

Stay inline · 5. You want it to spin up its own subagents.

Subagents can’t nest. Only your main chat is the conductor. If you need a chain, run it from the main conversation (Part 12).

Stay inline · 6. The subagents would need to talk to each other.

A subagent only ever reports back to the main chat. Two can’t message each other or share state. If the work needs agents to discuss and react in real time, that’s an Agent Team, not subagents (Part 15).

10 · Build Your Own, Step by Step

Two ways. Start with the easy one.

The easy way (recommended for your first)

1. Type /agents in Claude Code.
2. Choose to create a new agent.
3. Either fill in the form, or just describe what you want and let Claude write the file.
4. Pick its tools and model in the UI.
5. Save. It works immediately, no restart.

The manual way (when you know what you want)

1. Decide the one job this agent does. One job. If you catch yourself writing “and also,” split it into two agents.
2. Create the file: .claude/agents/your-agent-name.md (project) or ~/.claude/agents/your-agent-name.md (personal).
3. Write the frontmatter: name (matches filename, lowercase-hyphenated), description (the trigger rule: WHEN to use it, signal phrases, add “use proactively” if it should self-fire), tools (the minimum it needs), model (cheap if simple, sonnet/opus if it must think).
4. Write the body: Role (one sharp sentence), Workflow (numbered steps), Checklist/criteria (what to look for / what “done” means), Output format (tiers, line refs, word limits), Constraints (what NOT to do).
5. Keep the body short. Focused prompts beat long ones. A bloated body makes the agent lose track of its own rules.
6. Restart the session (if you wrote the file by hand), then test it and watch whether it routes correctly. First runs often reveal a vague description; tighten it.

11 · Six Ready-to-Copy Agents

Drop any of these into .claude/agents/. Adjust tools and model to taste.

---
name: code-reviewer
description: Expert code review specialist. Use proactively immediately after writing or modifying code. Triggers on "review my changes" or "check this PR".
tools: Read, Grep, Glob, Bash
model: sonnet
---

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 without asking for clarification

Review checklist:
- Code clarity and readability
- Well-named functions and variables
- No duplicated logic
- Proper error handling
- No exposed secrets or API keys
- Input validation present
- Adequate test coverage

Provide feedback in three tiers:
- Critical (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific file paths, line references, and concrete fix examples.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any error message or failed test.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture the full error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location in the code
4. Implement the minimal fix
5. Verify by running the failing test or reproducing the scenario

For each issue, return:
- Root cause (not the symptom)
- Evidence for your diagnosis
- The specific fix applied
- Verification result
- One-line prevention tip

Fix the underlying issue, not the surface symptom.

---
name: researcher
description: General-purpose research agent. Use when a task needs web search, reading documentation, or gathering external information before a decision. Do not use for questions already answerable from the codebase.
tools: WebSearch, WebFetch, Read
model: sonnet
---

You are a research analyst. Find accurate, current information and return clean briefs.

When invoked:
1. Pin down the exact question to answer
2. Search broadly, then read the best sources in depth
3. Cross-reference key claims across multiple sources
4. Flag where sources disagree

Return:
- Direct answer to the question
- Key supporting evidence (bullets)
- Source URLs for factual claims
- Important caveats or uncertainties

Return a summary only. Never dump raw search results or full page contents.

---
name: codebase-explorer
description: Explores and maps unfamiliar codebases. Use proactively before planning changes. Triggers on "how does X work" or "find where Y is implemented".
tools: Read, Grep, Glob, Bash
model: haiku
---

You are a codebase analyst. Understand codebases quickly and return structured maps.

When invoked:
1. Identify main entry points and top-level structure
2. Find the files relevant to the question or task
3. Map key dependencies and patterns
4. Note conventions (naming, error handling, testing)

Return:
- Key files and what they do (bullet list)
- Architecture summary (2-3 sentences)
- Relevant patterns or conventions
- Anything that would surprise an outsider

Keep your response under 500 words. Synthesize. Do not dump file contents.

---
name: doc-maintainer
description: Keeps documentation synced with code. Use proactively after changes to public APIs, function signatures, or user-facing behavior. Triggers on "update the docs".
tools: Read, Write, Edit, Glob, Grep
model: haiku
---

You are a technical writer keeping documentation accurate and current.

When invoked:
1. Read the relevant code files
2. Read the existing documentation
3. Identify what changed or is undocumented
4. Write or update docs to match the current code

Standards:
- Match the tone and format of existing docs
- Include code examples for API or signature changes
- Skip internal/private functions unless asked
- Flag anything uncertain instead of guessing

Return a summary of what you changed and why.

---
name: security-auditor
description: Reviews code for security vulnerabilities. Use proactively after writing auth, authorization, payment, or data-handling code. Triggers on "security review" or "check for vulnerabilities".
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior security engineer. Find real vulnerabilities, not style issues.

When invoked:
1. Run git diff to see recent changes
2. Read files involved in auth, authorization, or data handling
3. Search for common vulnerability patterns

Check for:
- SQL injection, XSS, command injection
- Authentication and authorization flaws
- Hardcoded secrets, API keys, credentials
- Insecure deserialization
- Missing input validation
- Insecure direct object references
- Dependency vulnerabilities

Return:
- Critical findings (file path, line number, severity, exploit scenario)
- Suggested fix for each
- Confidence level on each

Only report findings you can trace to specific code. No theoretical issues.

12 · Chaining and Orchestration

Where subagents go from “handy” to “a system.” A few rules first, then the patterns.

The composition rules

• Skills can call subagents. A skill (a saved workflow) can hand a step off to a subagent.
• Subagents can call skills. As long as the agent has the Skill tool. You can even preload skills with the skills: frontmatter field.
• Subagents CANNOT call other subagents. No nesting, on purpose, to prevent infinite loops. If you need a chain, the main conversation runs it: calls agent A, gets the result, then calls agent B with that result. The main chat is always the conductor.

The patterns

Sequential chain. Main chat runs a pipeline: researcher finds the files → reviewer checks the plan → main implements. Best for 2 to 3 step flows where each step feeds the next.

Fan-out / fan-in (parallel). Main chat fires several agents at once, waits for all, then combines. One explorer per module (auth, database, API) running simultaneously, then synthesize. This is where the speed gains live. Anthropic’s research system cut research time dramatically by fanning out 3 to 5 subagents at once.

Orchestrator-worker. One session that does no work itself. It only plans, delegates, reviews, and routes to the next worker: spec writer → architect review → implementer → code reviewer → final PR. Good for full feature pipelines. Put human checkpoints at the important handoffs so it can’t run off a cliff.

Builder/validator. A builder writes the code. A separate validator checks it in a fresh context with no memory of the reasoning, so it judges the result on its own terms. This is the strongest argument for subagents in serious work: the reviewer isn’t biased by having written the thing.

Worktree isolation. When several agents need to edit files at the same time, give each isolation: worktree so they work on separate copies and don’t collide.

13 · Limitations and Gotchas

Keep this list handy. Most “why did my agent do that” moments are on it.

• Fresh memory every time. A subagent doesn’t see your chat history or read files. It gets a task brief, its own system prompt, and your CLAUDE.md project rules (those still load). That’s it. (Built-in Explore and Plan even skip CLAUDE.md to stay fast.)
• It cannot ask you questions. It runs to completion; background ones auto-deny anything that would prompt you. Clarify before delegating.
• No nesting. Subagents can’t spawn subagents. Chain from the main chat instead.
• Only the final message comes back. All the intermediate work is gone once it finishes. That’s the feature, but you can’t go fish around in what it did.
• Startup overhead is real. Don’t use one for a task you could finish inline in 30 seconds.
• Hand-edited files need a session restart. Files made via /agents don’t.
• They cannot talk to each other. Two running agents are blind to each other. Everything routes through the main chat.
• Model names are lowercase. sonnet, not Sonnet. The field is model, not Model.

14 · Common Mistakes (and the Fix)

15 · Subagents vs. Everything Else

People mix these up constantly. Here’s the clean version.

16 · Cheat Sheet

The one sentence

A subagent is a second Claude you send off to do the messy work in its own window so your main chat stays clean.

The minimum file

---
name: my-agent
description: What it does and exactly when to use it. Add "use proactively" to auto-fire.
tools: Read, Grep, Glob
model: haiku
---
You are a [role]. When invoked: [steps]. Return: [format]. Do not: [constraints].

Where it goes

.claude/agents/ (team, shared via git) or ~/.claude/agents/ (just you). Make one fast: type /agents.

The four rules that matter most

1. One agent, one job.
2. The description is a trigger rule, not a label.
3. Give it the fewest tools it needs (read-only by default).
4. Cheap model for grunt work, smart model for thinking.

Save money

Match model to task (Haiku for scanning, Sonnet for building, Opus for hard reasoning), let the agent absorb the noisy context, and never spin one up for a 30-second job.

Remember the cost trap

Subagents start blank and re-gather context. Worth it for big or noisy work, wasteful for small tasks. Rule of thumb: 10+ files or throwaway output = use one.

The composition rules

Skills can call agents, agents can call skills, agents cannot call agents. The main chat is always the conductor.

Sources

Official

• Claude Code subagents docs
• Claude Code best practices
• How we built our multi-agent research system (Anthropic)
• How and when to use subagents (Anthropic)

Community deep-dives

• Tembo: Claude Code subagents
• PubNub: Best practices
• claudefast: Orchestration patterns
• Claudekit: Common mistakes

Build Claude Subagents Better Than 99% of People · Slide deck · Page glossary · samuelhuang.org