Subagents
Claude Code

Subagents

What they are, and how to build great ones
What they are. When to use one. How to build a great one. How to save money.
press → to start
Start here

A subagent is a specialist you send off

MAIN CHAT (you) SUBAGENT reads files, runs tests, digs go do a job summary only the answer comes back
Like a general contractor sending a specialist to inspect the foundation. They do the dirty work. You get the report.
The real reason they exist

It keeps your context clean

Do it yourself

memory fills up
Every file you read piles into your chat and stays there all session.

Send a subagent

mess stays here clean
It reads the pile in its own window. You get one clean summary.
This is the number one reason subagents exist. Not speed. Protecting your context.
Two kinds

Built-in vs the ones you build

Built-in

Ship with Claude Code. It reaches for them on its own.
Explore Plan General-purpose

Custom

your-agent.md The specialists you build. Each one is a little Markdown file in a folder. This guide is mostly about these.
You get value on day one from the built-ins. Building your own is the next level, not the entry fee.
The artifact

It is just one Markdown file

--- name: code-reviewer description: Review code after changes. Use proactively. tools: Read, Grep, Glob, Bash model: sonnet --- You are a senior code reviewer. When invoked: 1. Run git diff to see the changes 2. Review the modified files Flag: bugs, security holes, missing tests.
Settings on top (between the dashes). Instructions below (that text becomes its whole brain). That file IS the subagent.

Four settings, one that matters most

name→its ID. lowercase, hyphens. required
description→WHEN to use it. This is the trigger. required
tools→what it is allowed to touch
model→which brain it runs on (and how much it costs)
Only name and description are required. The description is the line that decides whether your agent ever fires.
Writing a great one

How to write one that actually works

Weak description "Security expert." Claude has no idea when to fire it. It just sits there, never triggering.
Trigger description "Reviews code for security holes. Use proactively after auth or payment changes." Now it fires on its own, at the right moment.
The body is its whole brain
Role → Numbered steps → Output format → What NOT to do
One agent, one job. Writing "and also"? That is two agents.
The part everyone gets wrong

Project-level vs global-level

Project

.claude/agents/  (in the repo)
  • Usable: only in this project
  • Shared: the whole team, through git
  • Belongs to: the codebase

Global

~/.claude/agents/  (home folder)
  • Usable: every project on your machine
  • Shared: nobody, just you
  • Belongs to: you
A project agent belongs to the codebase. A global agent belongs to you.
Subject-matter expertise

Each one is a specialist

security-auditorfinds vulnerabilities
test-runnerruns and fixes tests
doc-writerkeeps docs in sync
db-expertsafe queries only
One AI doing one thing really well beats one AI doing everything okay. Split the work across experts.
Better yet: borrow, don't build Whole collections of Claude Code subagents live on GitHub. Download the .md, drop it in .claude/agents/, and it just works.

How Claude picks one

Automatic Claude matches your task to an agent's description. The default.
Proactive Put "use proactively" in the description and it fires on its own.
By name @agent-name, or just "use the X subagent".
Whole session claude --agent name runs as the entire session.
Most of the time you don't choose. Claude reads each agent's description and routes for you.
Give it only what it needs

A read-only agent cannot break things

code-reviewer an agent that only looks, never touches
✓ Read ✓ Grep ✓ Glob ✕ Write ✕ Edit
Strip the Write tool and it is not a rule the agent chooses to follow. It is a thing it physically cannot do.

Save money: match model to job

Haiku $ · scan, search, docs Sonnet $$ · build, review Opus $$$ · deep reasoning, security
The trap: a subagent starts blank and re-gathers context. Worth it for big jobs. Wasteful for a 30-second task.
Where the real savings hide

Smart boss, cheap workers

THE LEAD Sonnet / Opus · $$ scan files Haiku · $ search code Haiku · $ summarize logs Haiku · $
  • The mix beats raw spend: one smart lead, a fleet of cheap workers
  • CLAUDE_CODE_SUBAGENT_MODEL forces every subagent onto a cheap model
  • maxTurns caps a wandering agent before it burns tokens
A multi-agent run can cost ~15x a plain chat. Big, noisy jobs only.
The most important section

When do you actually use one?

"Is this about to dump a pile of stuff into my chat that I'll never read again?"
Yes → subagent No → just do it inline
Almost every "should I?" is really this question. It always comes back to protecting your context.

The signals

Reach for one
  • It'll read a LOT of files
  • It'll spit out a wall of output
  • It's a job you keep repeating
  • Independent jobs, run in parallel
  • You want an unbiased reviewer
Skip it
  • It's one quick edit
  • Steps depend on each other
  • The agents would need to talk
  • It needs the whole conversation
  • It needs to ask you a question
Rule of thumb: 10+ files, or output you'll never re-read = subagent. Now scale the signal: dozens of parallel jobs, or a codebase-wide pass = a dynamic workflow.
Putting them together

The main chat is the conductor

MAIN CHAT agent A agent B agent C
✓ Skills can call agents ✓ Agents can call skills ✕ Agents can't call agents
Need a chain? The main chat runs it: call A, use the result, call B.
Scale it up → dynamic workflows Fanning out a few by hand is easy. For a big parallel job, a dynamic workflow writes the script that runs dozens of subagents at once, then merges the results.
Better results

The reviewer that can't be biased

you build it invested in it reviewer agent blank, never saw it honest verdict
Because the reviewer starts blank, it can't be swayed by how you built it. It judges the result cold, the way an outside engineer would. Builder writes, validator checks.
Same trick for research and planning: one agent does the work, a fresh one pressure-tests it.

The whole thing on one slide

One quick thing→just do it inline
A heavy or noisy side task→Subagent
Share it with the team→.claude/agents/ (in the repo)
Keep it just for you→~/.claude/agents/ (home folder)
Save money→cheap workers, one smart lead
Better results→let a fresh agent review your work
A giant parallel job→dynamic workflow (watch the bill)
Not sure?→"a pile I'll never re-read?" yes = subagent
Build your first one in seconds: type /agents.
1 / 18
← → to move