Claude Code Subagents: A Practical Guide

If you've used Claude Code for more than a week, you've probably hit the moment where a single conversation stops being enough. You want a second opinion on a diff, but the same Claude that wrote the code is anchored to the reasoning that produced it. Or you need to read forty files to answer one question, and you'd rather not bury your working context under the noise. That's what subagents are for.

This guide covers what a subagent actually is, when it's the right tool versus an inline skill, what it costs you in tokens, how to define one, and three concrete cases where it earns its keep. By the end you'll have a working agent file you can drop into a repo.

What a subagent is

A subagent is a separate Claude instance with its own context window and its own tool policy. You hand it a bounded task; it works in isolation and returns a result. Nothing from its scratch work lands in your main thread — only its final summary comes back.

That's the whole idea, and two properties fall out of it:

• Independence. The subagent isn't carrying your main thread's assumptions. When it reviews your change, it isn't invested in the code it just wrote, because it didn't write it. Fresh eyes are the point.
• Isolation. A big, noisy exploration — reading a large module, grepping across a codebase, running a battery of checks — happens over there, in its own context. Your working thread stays clean and only receives the conclusion.

You delegate to a subagent explicitly ("use the reviewer to check this diff"), or Claude delegates on its own when a task matches an agent's description.

Subagent vs. skill: when each wins

This is the distinction people get wrong most often, so it's worth being precise.

A skill is a procedure or body of knowledge pulled into your current conversation. It shares your context window and your tools. It changes how Claude behaves inline — same thread, same memory of everything you've been doing. Skills are cheap: they're text added to the prompt. They're the right call for a consistent way of working you want applied in place — "before you commit, run these gates," "refactor without changing behavior."

The catch: a skill can't give you an independent opinion. It's the same Claude, in the same thread, carrying the same assumptions. If those assumptions are the bug, a skill won't catch it — it shares them.

A subagent is what you reach for when the work benefits from that separation:

The honest rule: if the value is sharing your context, use a skill. If the value is not sharing it — independence or isolation — use a subagent.

The cost trade-off

Subagents aren't free, and pretending otherwise leads to bad instincts. A subagent spins up a full extra context window per run. It's slower than a skill and burns more tokens — it has to be brought up to speed on the task from scratch, do its work, and summarize back.

There's also a subtler cost: the handoff is lossy. The subagent returns a summary, not its full reasoning. Whatever it explored but didn't surface is gone. So you pay twice — once in tokens, once in detail — for the isolation you're buying.

The practical consequence: match the tool to the stakes. Delegating a one-line config tweak to a subagent is waste. Delegating a review of an auth change, or an exploration of a subsystem you don't know, is exactly the trade you want. Give the subagent enough context to work with up front, and expect to lose the detail it didn't choose to report.

How to define one

Subagents live in .claude/agents/<name>.md. Claude Code discovers them automatically — there's nothing to register. The frontmatter is the contract:

---
name: test-gap-finder
description: >
  Delegate after writing a feature to find untested paths. Returns a
  ranked list of specific missing test cases, each with the exact input
  that would exercise it.
tools: Read, Grep, Glob, Bash
---

# Test Gap Finder

You find what *isn't* tested, not what is. For the changed code:

1. Map each branch and error path.
2. For each, check whether an existing test drives it.
3. Report only genuine gaps — a concrete case plus the input that hits
   it. No filler, no invented findings to look thorough.

Three things carry most of the weight:

• The description is the trigger. It's what Claude reads to decide whether to delegate. Name the concrete situation and when to hand off. A vague description is an agent that never fires on its own.
• tools scopes what it can touch. Give a reviewer or research agent a read-oriented set like Read, Grep, Glob — you want findings, not edits, so leave out Edit and Write. Bash is the exception worth naming: it can run anything, including commands that write, so add it only when the agent genuinely needs to run tests or scripts, and rely on the agent's instructions to keep its use read-only. (Omit the tools line entirely to inherit the full tool set — reach for that deliberately, not by default.)
• Demand output worth reading. Because the handoff is lossy, tell the agent exactly what to return: ranked, concrete, with the failure path. "Don't invent findings" is a real instruction that improves signal.

An agent can also pin its own model in frontmatter. Give an adversarial or research agent a stronger reasoning model — it finds more — and keep a cheaper one for mechanical work.

Three cases where subagents earn it

1. Adversarial review. The headline use. After you make a change, delegate to a reviewer whose entire posture is "this change is broken until I can prove it isn't." Pass it both the diff and the intent — its method depends on knowing what the code is supposed to do so it can find where it doesn't. Because it's a fresh context, it catches the class of bug your own self-review is structurally blind to: the fake fix you're convinced works. A check-then-write that isn't actually atomic reads fine to the author and obviously wrong to an attacker who didn't write it.

2. Research and exploration. You need to understand how billing flows through a service you've never opened, or which modules import a function you're about to change. That's dozens of file reads producing one paragraph of conclusion. Do it inline and your main thread drowns in file contents you'll never look at again. Delegate it, and the subagent absorbs the noise and returns just the map.

3. Isolated refactor or investigation. A bounded, self-contained job — trace a bug across a subsystem, rename a concept through a package — that you want done without churning your primary context. The subagent runs the whole exploration in its own window and hands back the diff or the diagnosis.

Notice the pattern: every case is about the separation being the point, not a side effect.

Where to start

You don't have to write these from a blank file. The open-source claude-code-starter ships a working adversarial-reviewer subagent, a ship skill, and a bug-hunt workflow alongside a Next.js/TypeScript CLAUDE.md template — a concrete reference for the shapes described here. Read the reviewer's frontmatter and final "don't invent findings" instruction; those two lines are most of what makes a review agent useful.

The honest bottom line

Subagents buy you two things a skill can't — independence and isolation — and charge you a full context window plus a lossy handoff for them. That's a good trade on a load-bearing change and a bad one on a typo fix. Scope their tools to what the job needs, write the description for the delegation trigger, and tell them precisely what to return. Do that, and delegation stops feeling like ceremony and starts catching the things you'd otherwise miss.

Related guides

• Getting Claude Code to Write Tests That Catch Bugs
• 12 Claude Code Tips for Shipping Faster
• Claude Code vs Cursor: An Honest Comparison