Claude subagents: what they are, the built-in ones, and how to write your own
A Claude subagent is a specialized assistant that Claude Code (or the Agent SDK) hands a task to. Each one runs in its own context window, with its own system prompt, its own tool access and its own permissions, and only its final answer comes back to the main conversation. You define one in a markdown file in .claude/agents/ with a name and a description that tells Claude when to use it.
What are Claude subagents?
The Claude Code docs define subagents as "specialized AI assistants that handle specific types of tasks". Each one "runs in its own context window with a custom system prompt, specific tool access, and independent permissions".
That isolation is the reason they exist. When Claude searches a large codebase directly, every file it reads stays in your conversation. When a subagent does the search, those reads stay in the subagent's context, and your conversation receives only the summary. The docs list the benefits as preserving context, enforcing constraints, reusing configurations across projects, specializing behavior and controlling costs.
The built-in subagents: Explore, Plan and general-purpose
| Subagent | What it is for |
|---|---|
| Explore | A fast, read-only agent for searching and analyzing codebases |
| Plan | A research agent Claude uses during plan mode to gather context before presenting a plan |
| general-purpose | Complex, multi-step tasks that need both exploration and action |
You get these with no setup. Your own subagents add the specialists your project needs: a reviewer, a test runner, a migration expert.
How to create a Claude subagent
A subagent is a markdown file. The frontmatter configures it; the body is its system prompt:
```markdown
name: booking-test-runner description: Runs and fixes the booking service tests. Use proactively after any change under services/booking/. tools: Read, Edit, Bash, Grep model: sonnet
You run the booking service test suite, read the failures, fix the code (never the tests unless the test is wrong), and report what you changed in five lines or fewer. ```
Only name and description are required. Other fields include tools (an allowlist; leave it out to inherit the available tools), disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort and isolation.
Where the file lives decides its reach, highest priority first:
| Location | Reach |
|---|---|
| Managed settings | The whole organization |
--agents CLI flag |
This session only, not saved |
.claude/agents/ |
The current project, shareable through git |
~/.claude/agents/ |
All your projects |
A plugin's agents/ folder |
Wherever the plugin is enabled |
How Claude decides to delegate
Claude reads every subagent's description and delegates when a task matches, so the description works like a tool description: say what it does and when to use it. Phrases such as "use proactively" encourage delegation. You can also be explicit:
- in plain words: "Use the booking-test-runner subagent to fix the failing tests";
- with an @-mention, which guarantees that subagent runs for the task;
- for a whole session:
claude --agent booking-test-runner.
Subagents that Claude spawns from the main conversation start in the background by default, so you can keep working; a foreground subagent blocks until it finishes.
What a subagent knows: pass the context explicitly
A normal subagent starts fresh. It does not see your conversation; the only thing passed from the parent is the task prompt. If the subagent needs a file path, an error message or a decision you already made, that information must be in the prompt Claude writes for it.
This is the most common reason a subagent "does the wrong thing": it was never told. A fork is the exception: it inherits the whole conversation so far (start one with /subtask followed by the task).
Subagents in the Agent SDK and multi-agent systems
The Claude Agent SDK offers the same feature in code: define subagents in the agents option and Claude invokes them through the Agent tool. This is the building block of a multi-agent system: a coordinator that splits a job and hands each part to a specialist, such as a research system where one subagent searches the web, another analyzes documents and a third writes the report.
Nesting is allowed: by default a subagent can spawn its own, up to three layers below the main conversation, and the SDK lets you cap depth, concurrency and spend.
Subagents vs skills vs hooks
| What it is | Use it when | |
|---|---|---|
| Subagent | A separate assistant with its own context | A job whose details should not flood your conversation, or that needs different tools |
| Skill | Instructions loaded on demand | A repeatable workflow that runs in your conversation (or in a fork with context: fork) |
| Hook | Code at a fixed event | Something that must happen every time, without the model deciding |
Subagents on the Claude Certified Architect exam
Domain 1 of the CCAR-F exam spends two task statements on this: coordinator and subagent orchestration (1.2) and subagent invocation, context passing and spawning (1.3). Scenario 3, the multi-agent research system, is built on it, and task 3.4 names the Explore subagent for isolating verbose discovery. The trap to expect: assuming a subagent already knows what the coordinator knows. It doesn't; pass it explicitly.
One update since the guide: the tool Claude uses to spawn subagents shows as Agent in tool_use blocks, where older material says Task.
More in all articles.
Sources: Claude Code subagents; Subagents in the Agent SDK; Claude Certified Architect Foundations exam guide v1.0, task statements 1.2, 1.3 and 3.4.
FAQ
What are Claude subagents?
Specialized AI assistants that handle specific types of tasks. Each runs in its own context window with a custom system prompt, specific tool access and independent permissions, and returns only its final result.
Where do I put a subagent file?
In .claude/agents/ for the current project or ~/.claude/agents/ for all your projects. Only name and description are required in the frontmatter; the body is the subagent's system prompt.
What are the built-in subagents in Claude Code?
Explore, a fast read-only agent for searching and analyzing codebases; Plan, a research agent used during plan mode; and general-purpose, for complex multi-step tasks that need both exploration and action.
Do subagents see my conversation?
A normal subagent starts fresh: it gets its own system prompt and the task prompt from the parent, not the conversation history. A fork is the exception: it inherits the conversation so far.
Can a subagent start its own subagents?
Yes, by default up to three layers below the main conversation. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes the limit.