Claude Code subagents let you hand a focused task to a separate agent that runs in its own context window, then reports back. Instead of one conversation trying to hold your whole codebase, a failing test suite, and a refactor plan all at once, you delegate the research to a subagent and keep your main context clean. Used well, subagents are one of the biggest leverage features in Claude Code — and one of the most underused.
This guide explains what subagents are, how to create one, when they actually help, and how they differ from skills and MCP.
What is a Claude Code subagent?
A subagent is a specialized agent that Claude Code can spawn to handle a specific task independently. It has:
- Its own context window — separate from your main conversation, so heavy exploration doesn't bloat your primary context
- Its own instructions — a defined role and approach
- Its own tool access — you can scope which tools it's allowed to use
- A single job — it does the task, returns a result, and disappears
The main conversation stays focused. The subagent goes off, reads forty files or runs the test suite, and comes back with just the answer — not the forty files.
Why subagents matter
Context is the scarcest resource in any AI coding session. Every file Claude reads, every command's output, every dead end fills the context window. Once it's full, quality degrades.
Subagents solve this by isolating expensive work. A "test runner" subagent can run your suite, read the failures, and report "three tests fail, all in the auth module, here's why" — without your main conversation ever holding the raw test output. You get the conclusion; you don't pay the context cost.
This is also why subagents are good for parallel, independent work. Several subagents can investigate different parts of a problem at once, each in its own context, then report back.
How to create a subagent
Subagents are defined as markdown files, typically in .claude/agents/ in your project (or your user directory for personal ones). The structure mirrors how skills work — frontmatter plus instructions:
---
name: code-reviewer
description: Reviews code changes for bugs, security issues, and
convention violations. Use after writing or modifying code.
tools: Read, Grep, Glob
---
You are a focused code reviewer. When given changed files:
- Check for logic errors and edge cases
- Flag security issues (injection, auth, secrets)
- Verify the code matches project conventions
Report only high-confidence issues, ordered by severity.
The description tells Claude when to delegate to this subagent. The tools line scopes its access — a reviewer needs to read, not to run shell commands. Save the file and Claude Code can hand matching tasks to it automatically, or you can invoke it explicitly.
When to use a subagent
Subagents earn their keep when a task is:
- Context-heavy — exploring a large codebase, reading logs, analysing test output
- Independent — it doesn't need the back-and-forth of your main conversation
- Repeatable — code review, research, test triage, dependency audits
- Parallelizable — several investigations that can run at once
They're overkill for quick, conversational tasks. If you'd naturally just ask Claude inline, don't spin up a subagent.
Subagents vs skills vs MCP
These three get conflated constantly. They're different layers:
- Skills are instructions that load into the current context when a task matches — "here's how to do X well."
- Subagents are separate agents with their own context that you delegate a whole task to — "go figure out X and report back."
- MCP servers are external connections — "here's a tool to interact with GitHub/the database/the browser."
They compose. A code-review subagent can follow your code-review skill, using an MCP GitHub server to fetch the diff. Skill = the craft. Subagent = the delegation. MCP = the reach. And hooks are the fourth layer — deterministic shell commands the harness runs on events, for guarantees rather than judgement.
A practical workflow
A pattern that works well day to day:
- Main conversation: you describe the feature you're building
- Delegate to a research subagent: "trace how auth currently works and report the key files and flow"
- Subagent returns a tight summary; your main context stays clean
- You and Claude build the feature with that summary, not the raw exploration
- Delegate to a review subagent before committing
You get the benefit of deep exploration without drowning your main context in it. For more on getting the most from Claude Code, see our 5 techniques post.
FAQ
What is a subagent in Claude Code?
A subagent is a specialized agent Claude Code spawns to handle one task in its own separate context window, with its own instructions and scoped tools. It does the job, returns a result, and keeps your main conversation uncluttered.
How do I create a Claude Code subagent?
Create a markdown file in .claude/agents/ with frontmatter (name, description, optional tools) and instructions describing the agent's role. Claude Code can then delegate matching tasks to it automatically or on request.
How are subagents different from skills?
Skills are instructions that load into your current conversation to guide how a task is done. Subagents are separate agents with their own context that you delegate an entire task to. Skills shape the craft; subagents handle the delegation.
When should I use a subagent instead of just asking Claude?
Use a subagent for context-heavy, independent, or parallelizable work — large codebase exploration, test triage, code review. For quick conversational questions, asking inline is simpler and faster.
Do subagents share my main conversation's context?
No — that's the point. They run in a separate context window. They receive the task you delegate and return a result, without their exploration filling your main context.
Can subagents use MCP servers and skills?
Yes. A subagent can follow a skill and use MCP servers within its own context. The three layers compose: skill for how, subagent for delegation, MCP for external reach.
Go deeper
Subagents, skills, and MCP together turn Claude Code from a chat tool into a system. Our AI Foundations pack includes skills for designing multi-agent workflows and managing context handoffs.