Claude Code Subagents: A Practical Guide (2026)

by Jasmine, a dev who uses Claude Code and subagents every day.

What are subagents in Claude Code?

A subagent is a specialized instance of Claude that the main agent can spawn to handle a specific task, running in its own context window, with its own system prompt and its own set of tools, then reporting a condensed result back to the main agent. In short: instead of letting one Claude carry the entire job inside a single conversation, you split the work across small assistants - each one an AI agent specialized for a single role.

Picture the main agent as a tech lead. When a big job lands - say, "review the whole codebase for security" - the tech lead does not read every file in their own head. They hand it to a security specialist who reads, summarizes, and reports back. A subagent is exactly that specialist: it has a task description (the system prompt), it is granted certain permissions (tools), and when it is done it returns only the conclusion you actually need.

The core difference from just typing more instructions into the same session: Claude Code subagents have an isolated context. All the intermediate information a subagent has to read in order to do its job lives in its "head," and never spills back into the main session. You declare each subagent with a simple Markdown file placed in the .claude/agents/ directory, and Claude Code picks them up automatically.

How do subagents work? (context isolation)

The mechanism behind subagents is called context isolation. This is the real reason subagents are worth using, not just "spinning up another AI for show."

A typical run looks like this:

1. The main agent takes your request and decides which task should be handed off to a subagent.
2. It spawns the matching subagent along with a specific task description.
3. The subagent runs in its own context window - a "cognitive sandbox." It reads files, runs commands, and reasons through the problem, all in its own space.
4. When it finishes, the subagent returns only a condensed result (a summary, a list of bugs, a code snippet), instead of dumping the whole process into the main session.

You
 └─► Main agent (main context, lean)
 ├─► subagent: test-runner ──► returns: 2 tests failing
 ├─► subagent: security-scan ──► returns: 1 SQLi vulnerability
 └─► subagent: style-checker ──► returns: 5 lint warnings
 (each subagent = its own context window)

Because a subagent "swallows" the heavy context (reading dozens of files, long logs) and only exhales the essence, your main session keeps a clean context that lasts longer. This is partly about saving tokens (the main context does not balloon) and partly about quality: the main agent is not polluted by intermediate noise, so its reasoning stays sharper. The mechanism and scope are described by Anthropic in the official Claude Code Subagents documentation (accessed 08/2026).

It helps to distinguish this from manually opening a new chat tab. When you chat by hand across multiple sessions, you are the one copying results back and forth - slow and easy to drop. With subagents, the main agent orchestrates the whole flow: it decides what to hand off, to whom, and stitches the results back together automatically within a single turn of work. You never have to leave the terminal.

One thing people often misread: context isolation does not make a subagent "dumber." It is still the same model line you chose, just focused on exactly one task with exactly the tools it needs. Constraining the scope usually makes the output better, not worse - like giving one clear job to a specialist instead of asking one person to juggle ten things at once.

Create your first subagent - the .claude/agents file

This is the core hands-on part. There are two ways to create a subagent: use the /agents interface (recommended for your first time) or write the Markdown file by hand. Both produce the same thing - a file in .claude/agents/.

Step 1 - Open the agent manager

Inside a Claude Code session, type:

/agents

The interface lists your existing agents and lets you create a new one, pick a scope, choose a model, and limit tools through a menu. If you prefer direct control, you can skip this step and write the file yourself - the result is identical.

Step 2 - Choose a scope: project or user

There are two places to put an agent file, and choosing the right one matters:

• Project-level - .claude/agents/ inside the project folder. Applies only to this project, and can be committed to Git so the whole team shares it. Choose this for project-specific agents (for example, a reviewer that understands your team's conventions).
• User-level - ~/.claude/agents/ in your home directory. Applies across all of your projects. Choose this for agents you want handy everywhere (for example, a general doc-writer).

When names collide, the project-level agent takes priority over the user-level one.

Step 3 - Write the agent file (a real example)

Create the file .claude/agents/code-reviewer.md with the content below. The top is YAML frontmatter; the body is the subagent's system prompt:

---
name: code-reviewer
description: Review code for bugs, security, and maintainability. Use right after you write or change code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior-level code reviewer. Your job:
- Read the code that just changed (use Read/Grep/Glob, do NOT edit files).
- Find logic bugs, security holes, and hard-to-maintain spots.
- Rank findings by severity: critical / should-fix / suggestion.
- Return a short list with file paths and line numbers.
Do not run write commands, do not commit, do not change code.

Step 4 - Verify

Run /agents again to confirm that code-reviewer shows up in the list. That is it - you just built your first subagent. From now on, whenever you have just changed code, Claude can call it automatically, or you can call it directly: "use the code-reviewer subagent to look over what I just changed."

The frontmatter fields (name, description, tools, model)

The frontmatter decides how a subagent behaves. There are only four fields to remember:

Two tips worth their weight: (1) Write a clear description with verbs and situations ("Use right after..."), because this is what Claude uses to auto-call the right agent at the right time. (2) For a read-only agent, limit tools to Read, Grep, Glob - the subagent then physically cannot slip and edit or delete a file.

Calling and managing subagents

There are three ways to trigger a subagent:

1. Auto-delegation - Claude picks the right subagent based on the description field. You just work as usual, and when the context matches (for example, right after you finish editing code), Claude hands off to code-reviewer on its own.
2. Direct call - name the agent in your request: "use the code-reviewer subagent to check the payment module." This is the surest route when you know exactly what you need.
3. Manage via /agents - open the interface to list, edit, or delete agents; switch models, add or drop tools without opening files by hand.

If a subagent "never gets called" even though you think it should, the culprit is almost always a description that is too vague. Rewriting it to be specific fixes it.

Running in parallel and orchestrating multiple subagents

This is where subagents truly shine, and it is the part most guides skip. Because each subagent runs in its own context, the main agent can fan out multiple subagents at once over the same codebase.

Example: three subagents in parallel

Say you just finished a feature and want a full check before opening a PR. Instead of doing it sequentially, ask:

Run 3 subagents in parallel on the current branch:
- test-runner: run the full test suite, report which tests fail
- security-scanner: scan the code that just changed for vulnerabilities
- style-checker: check lint and conventions
Combine all three into a single report.

The three agents run independently, each reading what it needs, and then the main agent merges the three tight reports. You save both time and context.

On the token side, get the mechanism right before expecting "X percent savings." What you save is not the total token count - running three agents still costs tokens for all three. What you save is the main session's tokens: every test log, security-scan trace, and lint warning stays inside each subagent's context, and only a few lines of conclusion travel back. That is what keeps the main session from filling up early and lets you hold a longer train of thought. That is the real benefit - not a fixed percentage.

Multi-layer orchestration

One level up: the output of one subagent becomes the input to the next. A typical explore -> plan -> implement flow:

1) subagent "explorer": survey the codebase, return a module map + spots to change.
2) Feed that result to subagent "planner": lay out a step-by-step plan.
3) Feed the plan to subagent "implementer": execute it step by step.

This is a powerful orchestration pattern, but you have to understand one important limitation underneath it.

The limitation you must know

Subagents do not share context directly with each other and do not "talk" peer to peer. They only return results to the main agent, and it is the main agent that forwards information on to the next subagent. Every spawn is one token round-trip. So multi-layer orchestration has real power, but it also has a cost - do not overuse it. To understand exactly how subagents differ from Skills/Hooks/MCP, read the guide comparing Skills, Subagents, Hooks, and MCP.

A few subagent templates worth using right away

Four copy-paste templates, tweak lightly and go:

1. Read-only reviewer (absolutely safe)

---
name: safe-reviewer
description: Read-only code review that never edits files. Use to inspect before a merge.
tools: Read, Grep, Glob
model: sonnet
---
You only read and comment. Never run write commands. Return findings ranked by severity.

2. Test-runner

---
name: test-runner
description: Run the test suite and summarize failures. Use after editing code.
tools: Bash, Read, Grep
model: haiku
---
Run the project's tests, read the output, list failing tests with a short cause each.

3. Doc-writer

---
name: doc-writer
description: Write/update documentation and docstrings for new code.
tools: Read, Grep, Glob, Edit
model: sonnet
---
Read the code, write clear docs that match the repo's style. Do not change code logic.

4. Explorer

---
name: explorer
description: Survey an unfamiliar codebase, return an architecture map and entry points.
tools: Read, Grep, Glob
model: sonnet
---
Map out the modules, data flow, and the important files. Read only, never edit.

Notice all four templates: any agent that does not need to write is not granted write permission. That is a safe habit worth keeping.

How are subagents different from Skills, Hooks, and MCP?

These four building blocks get mixed up a lot. A quick way to tell them apart:

In short: subagents split the work, Skills teach a procedure, Hooks automate events, and MCP extends connections. The full comparison of all four building blocks goes deeper if you are still unsure which one to reach for.

Common mistakes and real limitations

Few blogs bother writing this section, but it is exactly what helps you use subagents correctly:

• Over-delegating. Splitting a tiny task (renaming one variable, fixing one line) into a subagent is counterproductive - the token round-trip and latency cost more than just doing it yourself. Subagents are for "context-heavy, result-light" work.
• A vague description means no auto-call. If the description is generic, Claude does not know when to hand off. Write out the specific situation to use it.
• Forgetting to limit tools. A reviewer that should only read but was granted write access can edit the wrong file. Always grant the minimum permissions.
• Burning tokens by fanning out too many agents. Running 5-6 agents in parallel sounds impressive, but each one is its own billable session. Fan out on purpose.
• When NOT to split: when a task needs the full context of the current conversation (for example, you are debugging a long flow where every earlier detail matters). A subagent cannot see the main context, so splitting it out loses the very context you need.

Skip the writing - AgentKit's 45 prebuilt agents

Writing a good subagent takes effort tuning the prompt and testing over and over. If you would rather have a ready-made library of specialized agents instead of writing from scratch, AgentKit's 45 prebuilt agents are an optional shortcut. It is a kit for Claude Code (not OpenAI's AgentKit - just a name collision), shipping 45 agents = 17 Engineer + 28 Marketing alongside 108+ skills. If you want to browse the agent catalog before deciding, read the overview of AgentKit's 45 prebuilt agents. The Engineer Kit is $99 (the site does not mention a recurring fee). That said, writing a few agents that match your own repo's conventions is still a foundational skill worth learning - the kit just helps you move faster.

Frequently asked questions (FAQ)

Do subagents cost extra money?

Yes, indirectly. Each subagent is a session with its own context, so it spends its own tokens; running several in parallel uses more tokens than a single session. In exchange, because the main context stays leaner, the overall run can still be efficient for context-heavy work.

How many subagents can run in parallel?

You can fan out several subagents at once, but you should cap it to real need (3-4 is usually reasonable for a review task). The more you fan out, the more tokens you burn and the harder they are to track.

Does a subagent remember the main conversation?

No. Each subagent runs in an isolated context window and cannot see the main session's history, except for whatever the main agent deliberately passes in. That is its strength (a clean context) but also a limitation to keep in mind.

How are subagents different from Skills?

Subagents are specialized sub-AIs that get assigned work and run independently; Skills are packaged instructions/procedures loaded in for Claude to follow. One "does the work for you," the other "teaches how to do it."

Should I put an agent at project-level or user-level?

Put it at project-level (.claude/agents/) for agents specific to a project that you want to commit for the team; put it at user-level (~/.claude/agents/) for agents you want across every project. When names collide, project-level wins.

Do I need Claude Code Pro?

Subagents are a Claude Code feature; you use them within whatever plan you already have. For plan details (Pro at $20/month, Max, and so on), see what Claude Code is.

Conclusion and next steps

Subagents turn Claude Code from a solo assistant into a small team: split the work, run in parallel, keep the context clean. Start simple with a read-only code-reviewer, then expand into orchestration once you grasp both its power and its limits. Read what Claude Code Skills are next to pair subagents with skills, or the comparison of the four building blocks to pick the right tool. And if you would rather not write from scratch, try the AgentKit bundle — now $149 (from $198) with its library of prebuilt agents.