Claude Code Subagents: The Complete Guide

Claude Code subagents are specialized assistants that the main Claude Code thread delegates a task to, each running in its own separate context windowwith its own system prompt and an optional restricted tool set. The subagent does its job — reviewing a diff, chasing a bug, running a test suite — then returns a result or summary to the main conversation. Context isolation is the whole point: the subagent starts fresh without the main thread’s clutter, and the main thread never has to absorb the subagent’s intermediate noise.

What are Claude Code subagents?

A subagent is a specialized assistant that Claude Code delegates a task to. Mechanically, it’s three things bundled together: a separate context window, a dedicated system prompt that defines its expertise, and an optional restricted tool set. When the main thread decides a subagent fits, it spins one up, hands over the task, lets it work in its own window, and receives a result back — not the full transcript, just the outcome.

That isolation is the feature, not an implementation detail. A long-running main conversation accumulates context: files you’ve read, dead ends you’ve explored, decisions you’ve already made. Dropping a fresh task into that soup makes the model less reliable. A subagent sidesteps the problem entirely — it begins with a clean slate and a single, well-defined job. Common examples shipped or built by teams include a code-reviewer, a debugger, a test-runner, and a data-scientist.

Subagents vs skills vs MCP

These three are easy to conflate because they all extend Claude Code, but they solve different problems. The cleanest mental model: a skill teaches how, a subagent runs a job in isolation, and MCP connects Claude to outside tools and data.

They compose rather than compete. A subagent can use skills and MCP tools inside its own window; a skill might recommend delegating a step to a subagent. For the deeper dive on the middle column, see the Claude Code skills guide — skills are procedural knowledge you load, subagents are jobs you delegate.

The .claude/agents file format

A subagent is a single Markdown file. The YAML frontmatter declares when and how to use it; the Markdown body isthe subagent’s system prompt — the instructions it runs with in its isolated window.

The body matters more than the frontmatter. It’s where you set the subagent’s role, its priorities, the checklist it should run, and the shape of the answer you want back. Treat it like onboarding a focused specialist who has never seen your main conversation — because that is exactly what it is.

Where subagents live (and which one wins)

There are two locations, mirroring the rest of Claude Code’s project-vs-personal split. Project subagents live in .claude/agents/<name>.md inside the repo and travel with it for everyone on the team. Personal subagents live in ~/.claude/agents/<name>.md and follow you across every project on your machine.

When a project subagent and a personal subagent share the same name, the project-level file wins. That precedence is deliberate: a repo can pin the exact reviewer or test-runner it expects, and a teammate’s personal override won’t silently replace it. You manage all of these interactively with the /agents command, which lets you create, edit, and inspect subagents without hand-editing files.

Automatic vs explicit delegation

Claude Code reaches for a subagent in one of two ways. With automatic delegation, the main thread reads each subagent’s descriptionand routes a matching task to it on its own — no prompting required. This is why the description field is the most important line in the file: vague descriptions get ignored, specific ones get used.

With explicit delegation, you name the subagent directly: “use the code-reviewer subagent on this diff.” Explicit calls are handy when you want a specific specialist regardless of how the main thread would have routed things. In practice you’ll lean on automatic delegation for the subagents you use constantly and explicit calls for the occasional, deliberate hand-off.

1. 1

   Claude matches the task to a subagent

   The main thread reads each subagent’s descriptionand routes a matching task to it — or you name one explicitly (“use the code-reviewer subagent”).
2. 2

   The subagent spins up in its own context window

   It begins with a clean slate and a single, well-defined job, working in isolation without the main thread’s clutter.
3. 3

   It returns a summary to the main conversation

   Only the result comes back — not the full transcript — so the main thread never absorbs the subagent’s intermediate noise.

How to create a subagent

The fastest path is the /agentscommand, which walks you through creating and editing subagents interactively. But because a subagent is just a Markdown file, you can also write one by hand. Here’s a complete .claude/agents/code-reviewer.md— frontmatter on top, system prompt in the body:

---
name: code-reviewer
description: >
  Expert code reviewer. Use immediately after writing or
  changing code to catch correctness, security, and style
  issues before they land.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:

1. Run `git diff` to see what changed; review only that.
2. Check, in order:
   - Correctness and obvious logic bugs
   - Security: injection, secrets, unsafe input handling
   - Error handling and edge cases
   - Naming, duplication, and dead code
3. Group findings as CRITICAL / WARNING / SUGGESTION.
4. For each, give the file, the line, and a concrete fix.

Be specific and terse. Return only the findings and fixes,
not a narrative of everything you read.

Note the restricted tools line: this reviewer can read files and run git, but nothing else. Omit that line and it would inherit every available tool, including MCP. The model field lets you route cheap, high-frequency subagents to a smaller model and save opus for the ones that need deep reasoning.

Best practices and trade-offs

Subagents are powerful but not free. The same isolation that makes them useful also means they start clean— with none of the main thread’s context — and they add latency, since spinning up a fresh window and handing work back and forth costs time. That shapes when to use them.

• Use them for well-scoped, isolatable jobs.Reviewing a diff, running tests, investigating one bug — tasks with a clear input and a clear deliverable are ideal.
• Keep tools to the minimum. An allowlist of the few tools a subagent actually needs is safer and keeps it focused on its job.
• Invest in the description.It’s the routing signal for automatic delegation; a precise one earns the subagent its keep.
• Don’t delegate tightly-coupled work.If a task needs deep awareness of the ongoing conversation, the clean-slate start works against you — keep it in the main thread.

If you’re thinking about context isolation as a strategy rather than a one-off, that’s the heart of context engineering for AI coding — subagents are one of the sharpest tools for keeping a window lean and on-task.

How do subagents relate to plugins?

Subagents don’t have to be authored one repo at a time. Claude Code pluginsbundle subagents alongside skills, slash commands, hooks, and MCP servers, so a single plugin install can drop a whole team of specialists into a project at once. If you’ve built a reviewer, a debugger, and a test-runner that work well together, packaging them as a plugin is how you share that set — instead of asking everyone to copy four Markdown files into .claude/agents/ by hand.

Managing subagents across projects

Here’s the practical snag once subagents become part of how you work. Personal subagents in ~/.claude/agents/ follow you everywhere, and project subagents in .claude/agents/travel with the repo — but the moment you want the same code-reviewerin ten repos, or you want your subagents’ conventions to match the rules you already maintain for Cursor and Copilot, you’re back to copy-paste and the drift that comes with it. That’s the same fragmentation problem covered in managing AI coding rules across tools and the rules-file comparison.

That’s exactly what Skillwrightis built for: keep your subagents, skills, and rules in one canonical library, version them once, and compile them out to every tool’s format — including Claude Code’s .claude/agents/— so the same reviewer and test-runner behave identically in every project and nothing drifts. Start from the templatesif you’d rather adapt a proven set than write each subagent from scratch.

Frequently asked questions