Key Takeaway
Claude Code subagents are specialized assistants defined as Markdown files in .claude/agents/, each with its own context window, system prompt, and scoped tools. They let a main session delegate focused work such as code review or research to an isolated context that returns only a summary, keeping the primary conversation clean and cost under control.
A single Claude Code session does everything in one context window, and that window is its scarcest resource. Read twenty files to answer one question and all twenty stay in context, crowding out the task you actually care about. Subagents are the built-in fix: a way to hand a slice of work to a separate assistant that thinks in its own window and hands back only the answer.
This guide covers what a subagent really is, how to create one, when delegation is worth it, and how subagents change what a session costs. The examples use Claude Code, but the same delegation pattern applies to any agentic coding tool that supports isolated sub-tasks.
What a subagent actually is
A subagent is a second Claude with its own context window, its own system prompt, and its own permissions. It cannot see your main conversation and your main conversation cannot see its working notes. The parent describes a job, the subagent does it in isolation, and only the final summary crosses back. That isolation is the whole point: bulky intermediate work never touches the main window.
Each subagent is a plain Markdown file with YAML frontmatter. Three fields do most of the work:
- A name and a description that Claude reads to decide when to route work to this agent, so write the description for the trigger, not for humans.
- An allowlist of tools, so a reviewer can read and grep but never write files or run shell commands.
- An optional model, so cheap high-volume work runs on a smaller model like Haiku while the main session stays on a stronger one.
Create your first subagent
The fastest path is to ask Claude to create the agent: say what it should do and whether it belongs to this project or to every project, and Claude writes the file for you. Since v2.1.198 the /agents command only prints a reminder to do exactly that; it no longer opens a creation wizard. You can also create the file by hand at .claude/agents/security-reviewer.md in your project, or under your home directory to make it available everywhere. The frontmatter configures the agent; the body is its system prompt.
A minimal, tightly scoped security reviewer looks like this:
---
name: security-reviewer
description: Reviews diffs for auth, injection and secret-handling issues
tools: Read, Grep, Glob
model: haiku
---
You are a security reviewer. Given a diff, report only concrete,
exploitable issues with a file:line and a one-line fix. Do not
comment on style. If you find nothing, say so plainly.Keep each subagent narrow: one job, one sharp description, and the smallest set of tools it needs. A vague catch-all agent gets invoked for the wrong tasks and quietly drags down the quality of everything it touches.
When delegation pays off
The rule of thumb is simple: delegate when the work generates far more tokens than the conclusion is worth keeping. Good candidates share that shape.
- Codebase exploration, where an agent reads dozens of files and returns a two-paragraph map instead of the raw dumps.
- Adversarial review, where a fresh agent sees only the diff and the acceptance criteria, not your reasoning, so it can catch what the author is blind to.
- Parallel research, where a lead agent spawns several workers at once. Anthropic reported that this orchestrator-worker setup beat a single agent by about 90 percent on their internal research evaluation.
- Repetitive scoped edits, where each file goes to its own short-lived agent so one failure does not derail the whole batch.
Wire subagents into a workflow
In practice the main session becomes an orchestrator. It plans the work, decides which pieces to delegate, and stitches the summaries back together. Your job is to describe each delegated task well: state the objective, the boundaries, and the exact shape of the output you want back.
Treat the delegation prompt like an API contract. A subagent that is told to return a ranked list of findings with file and line references gives you something you can act on; one told to please review the code gives you an essay you then have to parse.
Subagents do not share the main conversation's memory. Anything the parent already learned has to be restated in the delegation prompt, and a subagent cannot stop to ask you a follow-up mid-task, so hand it everything it needs up front or it will guess.
Cost and context discipline
Subagents are a spend lever that cuts both ways, and treating them as free is the fastest way to a surprising bill.
- They save context by keeping bulky file reads and tool output out of the main window, which slows the drift that fills a long session.
- They can raise total cost, because each agent re-reads the context it needs; multi-agent runs use far more tokens than a single chat, so reserve them for genuinely breadth-first work.
- Route low-stakes, high-volume subagents to a cheaper model and keep the orchestrator on your strongest one, so you pay top rates only where judgment matters.
Subagents turn Claude Code from one assistant into a small team you direct. Start with two you will actually use, a codebase explorer and a diff reviewer, keep each one narrow, and let the main session stay focused on the task instead of drowning in its own research.