Claude Code Subagents: When and How to Use Them

Claude Code subagents are separate Claude instances that the main agent can spawn to handle a task in an isolated context window. Each subagent gets its own instructions and its own tool access, works through the task independently, and returns only a final report to the main conversation. The intermediate churn -- every file it read, every dead end it explored -- stays out of your primary context.

That isolation is the whole value proposition, and also the whole cost. Used well, subagents let you run parallel work streams and keep a long session's context clean. Used carelessly, they double your token bill to do work the main loop could have done in place. This guide covers how subagents actually work, the built-in ones you already have, how to create custom subagents, and the delegation patterns that pay off in practice.

What are Claude Code subagents?

In a normal Claude Code session, one agent does everything in a single context window. Every tool result lands in that window and stays there, so on a long task, exploration output -- grep results, file contents, test logs -- crowds out the context you actually care about.

A subagent breaks that pattern. When the main agent delegates via the Task tool, Claude Code spins up a second agent with:

• Its own context window. It starts fresh. It does not see your conversation history, and the main agent does not see its tool calls.
• Its own system prompt. Built-in agents have predefined roles; custom subagents use the prompt you write.
• Its own tool access. You can restrict a subagent to read-only tools, or give it everything.
• A single deliverable. When it finishes, it returns one final report. That summary is all the main conversation pays for.

This matters because context is the scarcest resource in an agentic session. A subagent that burns 80,000 tokens exploring and returns a 500-token answer has effectively compressed that exploration 160x from the main loop's perspective.

Built-in subagents: Explore, Plan, and general-purpose

Claude Code ships with subagent types you can use without any setup. People lump all of these together as Claude Code agents, but they have distinct roles:

• Explore is a fast, read-only agent for codebase investigation. It can search and read files but cannot edit anything. Claude Code reaches for it when it needs to answer questions like "where is rate limiting enforced?" without pulling every candidate file into the main context.
• Plan does the investigation work behind plan mode, researching the codebase so the proposed plan is grounded in what the code actually does rather than assumptions.
• general-purpose is the everything agent: full tool access, capable of multi-step work including edits. It is the default for open-ended delegated tasks.

You do not have to wait for Claude to delegate on its own. Asking directly works:

Use a subagent to find every place we validate email addresses,
and report the file paths and validation approach used in each.

The main agent dispatches an Explore-style task, and your conversation receives just the findings.

How to create custom Claude Code subagents

Built-in agents are generic. Custom Claude Code subagents let you define specialists -- a code reviewer, a test runner, a migration checker -- with a scoped role, restricted tools, and a tuned prompt. Here is the full setup.

1. Create the agents directory

Project-level agents live in .claude/agents/ and travel with the repo. Personal agents live in ~/.claude/agents/ and follow you across projects.

mkdir -p .claude/agents

Project-level definitions win when names collide, and checking them into git means everyone on the team gets the same specialists.

2. Write the agent definition

Each agent is a markdown file with YAML frontmatter. The body is the agent's system prompt.

---
name: code-reviewer
description: Reviews code changes for bugs, security issues, and
  convention violations. Use proactively after significant edits.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer for this repository.

When invoked:
1. Run git diff to see recent changes.
2. Review only the changed files.
3. Check for correctness bugs, missing error handling,
   security issues, and violations of project conventions.

Report findings ranked by severity. For each finding, include
the file, the line, and a concrete failure scenario. If nothing
is wrong, say so briefly -- do not invent problems.

3. Scope the tools deliberately

The tools field is a least-privilege control. A reviewer needs Read, Grep, Glob, and maybe Bash for running the test suite -- it should not have Edit. Omit the field and the agent inherits all tools, which is fine for a general worker but sloppy for a specialist. An agent that cannot write files cannot "helpfully" fix things you only asked it to report.

4. Pick a model per agent

The model field lets you match cost to difficulty. Mechanical work -- log scanning, formatting checks, running tests and summarizing failures -- runs fine on a faster, cheaper model. Judgment-heavy work like architecture review deserves your strongest model. Leaving it unset inherits the main conversation's model.

5. Test with an explicit invocation

Before trusting automatic delegation, call the agent by name:

Use the code-reviewer subagent to review my uncommitted changes.

Read the report it returns. If the output is vague, sharpen the system prompt's instructions about format and scope. You can also run /agents to list, inspect, and edit registered agents.

6. Tune the description for automatic delegation

The description field is not documentation -- it is the trigger. The main agent reads it when deciding whether to delegate, so write it the way you would write a routing rule: what the agent does, and when it should be used. Phrases like "use proactively after significant edits" meaningfully increase how often Claude hands work over without being asked.

When to delegate: real wins vs token-cost traps

Delegation is not free. Every subagent starts with zero context, so it re-reads files the main agent already read, and you pay for its entire loop plus the dispatch overhead. The economics only work when isolation or parallelism buys you something.

Delegate when:

• The search space is large and the answer is small. "Find how auth middleware is wired across this monorepo" might touch fifty files. A subagent absorbs those fifty files and returns a paragraph.
• Work parallelizes cleanly. Four packages with independent lint failures can be fixed by four agents at once instead of one agent sequentially.
• You want fresh eyes. A reviewer subagent has none of the writer's context -- which is exactly what makes its review honest. It cannot rationalize a bug because it never saw the reasoning that produced it.
• The output is noisy. Long test runs and log digging generate thousands of lines you never want in your main context. Let a subagent read them and report the three failures that matter.

Keep it in the main loop when:

• The task is a small, targeted edit. Renaming a function or fixing one file through a subagent means paying startup and re-reading costs for work the main agent could finish in two tool calls.
• The task depends on conversation history. Subagents do not see your chat. If the task only makes sense given twenty minutes of prior discussion, you will spend more tokens re-explaining than you save.
• Steps are tightly sequential. Each delegation is a round trip. A pipeline of five dependent steps through five subagents is slower and more expensive than one agent doing all five.

A useful rule of thumb: delegate when the intermediate work is bulky and the deliverable is compact. When you do delegate, prompt like you are writing a ticket -- context, concrete task, expected output format. A vague brief produces a wandering agent, and you pay for the wandering.

Orchestration patterns for parallel agents in Claude Code

The single biggest speed win with parallel agents in Claude Code comes from dispatching independent tasks concurrently. When the main agent issues several Task calls in one turn, they run at the same time. A few patterns come up repeatedly:

Fan-out, fan-in. Split independent work, dispatch it all at once, aggregate the reports:

Launch three subagents in parallel:
1. Audit apps/web for unused exports.
2. Audit apps/api for unused exports.
3. Audit packages/shared for unused exports.
Each should report a file-by-file list. Combine the results
into one cleanup plan when all three finish.

The key constraint: give each agent a disjoint scope. Parallel agents share no memory and do not coordinate, so two agents editing the same files will silently clobber each other. Partition by directory, package, or concern.

Research first, implement second. Send Explore subagents out to map the territory, then implement in the main loop with a clean context and a distilled brief -- instead of letting the main agent research its way into a bloated context before writing any code.

Writer and reviewer. Have the main agent implement, then dispatch a reviewer subagent over the diff. Because the reviewer starts cold, it checks the code against the codebase rather than against the writer's intentions.

Files as shared state. When stages genuinely must pass data, have each subagent write its findings to a scratch file that the next stage reads. Conversation summaries are lossy; files are not.

One honest caveat: parallelism multiplies spend. You are buying wall-clock time and context isolation, not efficiency -- budget accordingly.

Subagents vs skills vs slash commands

Claude Code has three customization mechanisms that get conflated constantly. The subagents vs skills question in particular trips people up, because both live under .claude/ and both encode expertise. They solve different problems:

The short version: skills teach the agent you are already talking to, commands script the prompts you type anyway, and subagents are extra workers. They compose well -- a slash command can kick off an orchestration, a skill can teach the main agent how your team wants delegation done, and subagents execute the pieces. For a deeper treatment, see our full breakdown of skills vs commands vs subagents and the Claude Code skills guide.

One practical difference: skills have a portable, tool-agnostic distribution story. A skill published to localskills.sh installs into .claude/skills/ for Claude Code and into the native rule formats of Cursor, Windsurf, and other tools from the same package -- so the knowledge half of your setup can be shared and versioned across the team, while agent definitions stay in your repo's .claude/agents/ directory under normal version control.

FAQ

Do subagents share context with the main conversation?

No. A subagent starts with a fresh context window and does not see your chat history, and the main agent sees only the subagent's final report. Delegation briefs therefore need to be self-contained: anything the subagent must know has to be in the dispatch prompt.

Can a subagent spawn its own subagents?

No. Subagents cannot delegate further -- orchestration is the main agent's job. If a task seems to need nested delegation, restructure it as multiple flat tasks the main loop dispatches directly.

How do I make Claude Code use a subagent automatically?

The description field in the agent's frontmatter drives automatic delegation. Make it specific about what the agent does and when it applies, and include an explicit cue like "use proactively after significant code changes." Vague descriptions rarely trigger; routing-rule descriptions do.

Are subagents cheaper than doing the work in the main loop?

Usually not for small tasks -- a subagent re-reads files and repeats setup the main agent already paid for. They become economical when the intermediate work is large relative to the deliverable, or when parallel execution saves enough wall-clock time to justify the extra tokens.

Should I use a subagent or a skill for team conventions?

A skill. Conventions are knowledge the main agent should apply while it works, not a task to hand off. Reserve subagents for isolatable units of work; encode standards as skills so they load into whatever agent is doing the writing. Our Claude Code tips post covers how to layer that project context effectively.

---

Put your agent setup to work across the team

Subagents live in your repo, but the skills and conventions that guide them deserve a real distribution story. Sign up for localskills.sh to publish your team's skills once and install them into Claude Code, Cursor, Windsurf, and more.

npm install -g @localskills/cli
localskills login
localskills install your-org/your-skill --target claude cursor