A subagent in Claude Code is a smaller, focused assistant that the main agent hands work to. It has its own system prompt, its own set of allowed tools, and — if you want — its own model. The point isn’t novelty. It’s that a subagent runs in a separate context window, so all the noisy exploration it does never lands in your main conversation.
That separation is the whole game. When the main thread asks a subagent to “find every place we validate email addresses,” the subagent can read twenty files, follow imports, and burn through tokens figuring it out. What comes back is a tidy summary. Your main context stays clean and on-task.
This guide covers what subagents are, where they live, what goes in the file, how Claude decides to use one, and how the model field doubles as your main cost lever. There’s a complete example agent file at the end.
Where subagents live
Subagents are plain markdown files in one of two places:
Subagent locations
| Scope | Path |
|---|---|
| Project | .claude/agents/ |
| User | ~/.claude/agents/ |
On Windows, the user path is C:\Users\YourName\.claude\agents\. If you work mostly in WSL, the home directory is the Linux one — ~/.claude/agents/ inside your distro — not the Windows profile. That distinction trips people up when an agent “disappears” after switching shells. For the WSL side of the setup, see the WSL install guide.
When a project agent and a user agent share the same name, the project one wins. That’s useful: a repo can ship an opinionated reviewer that overrides whatever you keep personally.
You can see what’s currently available — built-in and custom, project and user — with the /agents command, which lists every agent Claude can delegate to in the current session along with where each one is defined. It’s the quickest way to confirm a new file was picked up and to spot two agents with names that clash.
What goes in the file
A subagent file is YAML frontmatter followed by a system prompt. The frontmatter has four fields that matter:
Subagent frontmatter
| name | Unique identifier, lowercase with hyphens |
|---|---|
| description | When this agent should be used — drives delegation |
| tools | Comma-separated tools it's allowed to use (optional) |
| model | Model for this agent, or inherit (optional) |
The body below the frontmatter is the system prompt. This is where you tell the subagent what its job is, how to approach it, and what to return. Treat it like onboarding a specialist who knows nothing about your conventions — be explicit.
If you omit tools, the subagent inherits the tools available to the main thread. If you omit model, behavior depends on your configuration; you can also set it to inherit the session model explicitly. The full set of tool names you can list is in Anthropic’s tools reference.
How delegation works
Here’s the part people miss: you don’t usually call a subagent. Claude does.
When the main agent picks up a task, it looks at the description of every available subagent and decides whether one fits. If your description says “Use this agent to review code changes for bugs and security issues after writing code,” Claude will reach for it right after editing files. If the description is vague — “helps with code” — delegation gets unreliable, because there’s nothing concrete to match against.
You can also be explicit. Asking “use the test-writer subagent to cover the new endpoint” forces the hand-off. But for day-to-day flow, a sharp description is what makes automatic delegation work.
The subagent receives the task, works in its own context, and returns a result. The main thread continues from there. Because the contexts are isolated, the main agent never sees the subagent’s scratch work — only the answer.
Automatic vs explicit invocation
Two ways a subagent gets used. Automatic delegation is Claude deciding, on its own, that a subagent fits the task — driven entirely by the description. Explicit invocation is you naming the agent in your request: “have the code-reviewer check this.” Explicit invocation is handy when you’re testing a new agent or when you want a specific one even though the task is ambiguous. In normal use, a good description means you rarely have to name agents by hand.
What subagents don’t solve
It’s worth being clear about the limits. A subagent doesn’t make the model smarter; it just isolates context and lets you route work. It also adds a hop — the main thread has to hand off and wait for a summary — so for a trivial one-line task, delegating is slower than just doing it. And subagents aren’t persistent services; each delegation is a fresh run with no memory of previous ones beyond what’s in the project files. Skills and MCP servers cover different needs, which is why skills vs MCP vs subagents is worth reading before you reach for the wrong tool.
Model routing is the cost lever
The model field is where subagents quietly save you money. Not every task needs your strongest model. Searching the codebase, reading logs, gathering context, running a linter and summarizing the output — that’s high-volume, low-judgment work. Point a cheaper, faster model at it.
Keep the heavier model for the main thread, where planning and the actual code changes happen. A reasonable split looks like this:
Model tiers by job
| Job | Model tier |
|---|---|
| Exploration, search, context gathering | Cheap/fast model |
| Code review, test writing | Mid-tier model |
| Main thread: planning and editing | Strongest model |
Because exploration subagents tend to do the most token-heavy reading, moving just those to a cheaper tier often makes the biggest difference. If you want to push this further and route by provider as well as tier, the Claude Code Router setup and the broader cheap-model guide cover that.
Built-in vs custom
Claude Code can delegate to general-purpose helpers on its own — a general task runner for open-ended work, for example. These exist without you doing anything.
Custom subagents are the ones you write for your specific workflow. The common, durable ones:
- A code reviewer that reads a diff and flags bugs, missing error handling, and security issues.
- A test writer scoped to your test framework and file layout.
- A debugger that reproduces a failure, reads logs, and proposes a fix.
- A context-gatherer that maps how a feature works across files and reports back.
For a full rundown of which patterns pay off, see the best Claude Code subagents to set up. And for how subagents relate to Skills and MCP — which solve different problems — see skills vs MCP vs subagents.
Chaining subagents
Subagents are most useful when one feeds the next. A natural chain on a feature: a context-gatherer maps the code, the main thread plans and edits, a test-writer covers the change, and a code-reviewer checks the diff. Each step runs in its own context and hands a clean result back to the main thread, which keeps the primary conversation focused on decisions rather than the mechanics of each step. You don’t wire this up explicitly — clear descriptions let Claude reach for the right agent at the right moment — but it helps to design your agents knowing they’ll be used together.
A complete example agent file
Here’s a working code-reviewer subagent. Save it as .claude/agents/code-reviewer.md in your project:
---
name: code-reviewer
description: >
Use this agent to review code changes for bugs, missing error
handling, and security issues. Run it after writing or modifying
code, before committing.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior engineer doing a focused code review. You are given a
set of recent changes to review.
Your job:
1. Read the changed files and enough surrounding code to understand them.
2. Look for real defects: logic errors, unhandled errors, race conditions,
off-by-one bugs, and inputs that aren't validated.
3. Flag security issues: injection, hardcoded secrets, missing authz checks.
4. Note anything that breaks the project's existing conventions.
Rules:
- Report only issues you can point to with a file and line. No vague advice.
- Rank findings by severity: blocker, should-fix, nitpick.
- If the change looks clean, say so plainly. Don't invent problems.
- Do not edit files. Report findings only.Note the scoping. This agent gets Read, Grep, Glob, and Bash — enough to read code and run checks — but no write or edit tools, because a reviewer shouldn’t be changing files. That tight scope is deliberate, and it’s a habit worth keeping: give a subagent only what its job requires.
To build your own from scratch and avoid the usual missteps, walk through how to build a custom subagent.
Wrapping up
Subagents are Claude Code’s way of doing focused work without polluting the main conversation. Each one is a markdown file with a name, a description that drives delegation, a scoped tool list, and an optional model. Put them in .claude/agents/ for the project or ~/.claude/agents/ for yourself, write a sharp description so Claude knows when to delegate, and use the model field to push cheap work to a cheap model.
Start with one — a code reviewer or a context-gatherer — get the description and tool scope right, then add more as patterns repeat in your workflow.
