Build a Team of Specialists: Subagents in Claude Code

Agents · Working with AI

Here is the problem subagents solve, and it is one you have felt. You are three hours into a session. Claude Code has read forty files, summarized two design docs, and is drafting a migration. You ask it to also check whether any of this touches the auth pipeline, and you watch the context window swell past seventy percent. A couple of prompts later it is auto-compacting, and the thread you were holding in your head is gone.

A subagent fixes this by handing the side quest to a separate instance. That instance has its own context window, its own tools, its own model, and its own system prompt. It does the narrow job in isolation and returns only the result. The search output, the file dumps, the dead ends: none of it lands in your main conversation. Think of the parent session as the lead and the subagent as a contractor brought in for one job.

This piece is about building good ones, why narrow beats broad every time, four examples worth stealing, and whether any of this carries over to other tools. It does, more than you might expect.

The shape of a subagent

A subagent is a Markdown file. The YAML frontmatter at the top is the configuration; the Markdown body below it is the system prompt the agent runs under. Here is the minimal shape, the official code-reviewer:

---
name: code-reviewer
description: Reviews code for quality and best practices. Use after any code change.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the diff and give specific,
actionable feedback on quality, security, and best practices. Group findings
by severity. Show the exact line, the problem, and the fix.

Drop that at .claude/agents/code-reviewer.md in a project, or ~/.claude/agents/ to have it everywhere. Only name and description are required. Everything else has a sensible default.

A few things about the fields are worth knowing, because they are where the behavior actually lives.

The description is load-bearing. Claude reads it to decide when to hand work over on its own, so write it as a trigger rather than a label. "Reviews code for security and quality. Use after any code change" delegates far more reliably than "code reviewer." If you want the agent to fire without being asked, the description is how.

The tools list is your safety scope. Name the tools and the agent gets only those. Leave it out and the agent inherits everything the main thread can touch, MCP servers included. For a reviewer that should never change anything, granting only Read, Glob, and Grep is the difference between an agent that reads your code and one that can rewrite it.

The model is per agent. Cheap, high-volume jobs can run on Haiku; a reasoning-heavy security pass can run on Opus while your main session stays on Sonnet. As of v2.1.196 you can also set CLAUDE_CODE_SUBAGENT_MODEL to inherit so children match the parent.

The body is the whole prompt. A subagent does not see Claude Code's normal system prompt. Whatever the agent needs to behave correctly has to be in that body. Treat it as briefing a contractor who has never seen your project.

One gotcha catches everyone once. File-based subagents load at session start. Edit the file on disk and the change does not take until you restart. Agents you create or edit through the /agents interface take effect at once. (Note that as of v2.1.198 the /agents command no longer runs an interactive wizard; it points you at asking Claude to write the file or editing .claude/agents/ yourself.)

Why narrow beats broad

The instinct, once you have the mechanism, is to build one big helper that reviews and tests and documents and refactors. Resist it. Narrow wins for reasons that compound.

A narrow agent has a clear trigger. Claude can tell when a security review is wanted. It cannot tell when your do-everything agent is wanted, so it either over-delegates or never delegates.

A narrow agent has a tighter prompt. Instructions for one job are sharper than instructions hedging across five, and the output shows it.

A narrow agent has a safer tool scope. A reviewer needs to read. A test runner needs to run tests. A single agent doing both needs both sets of powers at once, which is exactly what you were trying to avoid.

And narrow agents chain. A reviewer that finds problems can hand to a fixer that repairs them. You cannot chain two halves of the same blurred agent. Scope each to one job, and you can compose them into a pipeline where each step does one thing you can name.

The rule I use: if you cannot write the description as a single trigger condition without the word "and," the agent is doing too much. Split it.

Four worth stealing

These are the specialists I reach for most. Each is deliberately scoped to one job, with a tool list to match.

A diagram of a subagent team. At the top, the main session
is the lead that stays focused and keeps its context, delegating by matching each agent's
description. Below it, four scoped agents: security-reviewer on Opus, read-only, tools Read, Glob,
Grep; test-validator on Sonnet, run and report, with Bash added; explorer on Haiku, read-only; and
impact-checker on Sonnet, inspect and report, with Bash. Each returns only a summary, so file dumps
never touch the main context. At the bottom, a chain shows a code change flowing to the security
reviewer, which finds a SQL injection and hands off to a fixer, alongside four rules for a good
subagent: one job, description written as a trigger, narrowest tools, and a self-contained prompt. — One lead session delegating to four scoped specialists, each returning only a summary.

Security reviewer

Read-only by design. It should find problems, never change code, and never run anything.

---
name: security-reviewer
description: Audits changes for security flaws: injection, auth, secrets, SSRF.
  Use after any change that touches input handling, auth, queries, or network calls.
tools: Read, Glob, Grep
model: opus
---

You are a security reviewer. Examine the diff ONLY for security problems.
For each of injection, broken access control, secrets in code, SSRF, and unsafe
deserialisation, state where the risk is or say there is none. For every finding:
the file and line, why it is exploitable, and the fix. Do not comment on style.
Do not modify code. If you find nothing, say so plainly.

Running the audit as its own instance, on a stronger model, with no write access, is the whole point. It reasons hard about one thing and it cannot break anything while doing it.

Test validator

It runs the suite and judges whether the tests are worth anything. Writing them is a different job.

---
name: test-validator
description: Runs the test suite and checks that tests actually assert behavior.
  Use after tests are added or changed, before merging.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You validate tests. Run the suite and report pass or fail with the command used.
Then, for each new or changed test, ask: what change to the implementation would
make this test fail? If you cannot name one, flag the test as hollow. Call out
tests that assert on mocks, re-assert the implementation, or only check that a
value is truthy. Report; do not fix.

This one is worth the overhead because a green suite is not the same as a suite that would catch a regression, and a fresh instance whose only job is to be skeptical about that is better at it than your main session, which just wrote the code and wants to move on.

Codebase explorer

The classic context-saver. It goes and reads twenty files so your main session does not have to.

---
name: explorer
description: Traces how something works across the codebase and reports back a map.
  Use for "where is X handled" or "how does Y flow through the system."
tools: Read, Glob, Grep
model: haiku
---

You map code. Given a question, find the relevant files and trace the path.
Return a concise map: the entry point, the files involved in order, the key
functions, and where the important decisions happen. Quote only the lines that
matter. Do not dump whole files. End with the shortest answer to the question.

Haiku is deliberate. Exploration is high-volume, low-stakes reading, and the summary it returns is small even when the reading was large. That summary is all that reaches your main context, which is the saving.

Migration or dependency checker

A focused pre-flight for the change that always breaks something two directories away.

---
name: impact-checker
description: Finds everything a proposed change would affect before it is made.
  Use before renaming, changing a signature, or bumping a dependency.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You assess blast radius. Given a proposed change, find every call site, import,
test, and config that depends on the thing being changed. Report them grouped by
file, note which are public API, and flag anything that would break silently
rather than at compile time. Recommend an order of changes. Do not make edits.

Notice the pattern across all four. Three are read-only; the two that get Bash still say "report, do not fix" in the body. The tool list and the prompt work together: the list makes a mistake impossible, and the prompt makes the intent clear.

The cost, stated plainly

Subagents are not free, and the write-ups that skip this do you no favors. Each one runs in its own context window, which means its own tokens. There is no separate billing (it is the same account and the same model rates), but a subagent-heavy workflow can burn on the order of several times the tokens of a single-threaded session, because every child maintains its own context. Delegation also adds latency: the parent waits for the child to finish.

So delegate for a reason. The good reasons are isolation (keep a big, messy job out of the main thread), specialization (a scoped prompt and a specific model), and parallel exploration (several read-only searches at once). Spawning a subagent to do a thirty-second edit your main session could have done is pure overhead. Match the tool to the job.

Does this work for Codex and others?

Yes, and that surprised me a little. This stopped being a Claude Code-only idea in 2026.

OpenAI's Codex moved subagents to general availability in March 2026. The model is close to Claude Code's on purpose: it ships default subagents (an explorer, a worker for many small parallel tasks, and a default), and it lets you define custom ones. The format differs: Codex uses TOML files in ~/.codex/agents/ rather than Markdown with YAML, and you can pin each custom agent to its own model, including the faster snapshots for cheap child work. You then reference them by name in a prompt, much as you do in Claude Code: tell it to have one agent reproduce a bug, another trace the code path, and a third make the fix.

The shared vocabulary matters more than the file format. Both tools converged on the same core idea: a parent session that delegates to scoped children, each with its own context, model, and instructions, returning a summary rather than a pile of intermediate work. Skills, MCP, and hooks sit alongside subagents in both. So the thinking here ports even where the syntax does not. If you design good specialists (one job each, a description written as a trigger, the narrowest tools that do the work), you are building something that carries across tools, not a trick that only works in one.

One caveat worth flagging in both: an agent that writes files needs isolation, or two of them running at once will collide. That is the same worktree discipline that parallel agents always need, and it does not go away just because the workers are subagents.

The habit underneath all of it

Every good subagent is the same small act of restraint: decide the one thing this agent does, give it only the tools that job needs, write the description so the tool knows when to call it, and put everything it needs to behave in the prompt because it starts blind. Do that and you get a team of narrow specialists you can trust and compose. Skip it and you get one vague helper that delegates at the wrong times and holds powers it never needed.

The skill is not writing a clever agent. It is drawing the boundary tightly, and knowing which job is worth handing off in the first place.