Claude Code Subagents: Structure, Five Roles, and Orchestration

What Is a Subagent in Claude Code, and Why Isn’t It “Just Another Skill”?#

The Claude Code documentation defines it this way:

Put in terms an entrepreneur would understand: imagine a real estate agency. There is a director, a marketer, a lawyer, and sales managers. One employee switching among all these roles is not a team; it is an overloaded person. A team emerges when each person has their own context and area of responsibility, while the director only assigns tasks and brings the results together.

Subagents in Claude Code work the same way. The main chat is the director. A subagent is a specialist with a narrow task, its own context, and set of tools. When a task matches a specialist’s description, the director delegates it—and does not get bogged down in the details.

5 Goals Anthropic Built Subagents For

Anthropic’s documentation lists exactly five reasons to create your own subagent:

The most practical item on this list for a non-programmer is cost control. You can send a heavy research task to the inexpensive Haiku model while continuing the main conversation on Sonnet or Opus. Token savings are directly proportional.

Check Nesting Support for Your Installed Version

The templates in this guide use one main session delegating directly to workers. Do not treat older documentation saying “subagents cannot spawn other subagents” as a timeless rule: nesting behavior depends on the installed version and permitted tools. The separate nested-subagent guide discusses a version-specific recipe. Verify support in your installation before planning deeper delegation.

How Does a Subagent Differ from a Skill, Slash Command, and Hook?#

The previous guide about Skills explains that skills and slash commands in Claude Code have effectively merged into one format. But a subagent is a different entity—not simply “a bigger skill.”

A summary table of the four mechanisms:

Put simply: skills are recipes; subagents are specialized colleagues.

In practice, it works like this: skills activate automatically when their description matches the task, while subagents are invoked explicitly—either the main chat decides to delegate or you call one by name.

Decision Tree: “Which One Should I Choose?”

When you think, “I need Claude to do X,” run it through these four questions:

1. Is this knowledge that should always be available? For example, “we localize into the user’s preferred language,” or “we don’t use em dashes.” Put it in CLAUDE.md.
2. Is this a triggered methodology that you perform manually now? For example, “I write a sales report every Monday.” Make a skill.
3. Is this a task that will consume the main chat’s context, or can it be run in parallel? For example, “deep research across 30 sources,” or “a security audit while I write a new feature.” Make a subagent.
4. Do you need an automatic response to an event in Claude Code? For example, “run the linter after every Edit.” Write a hook.

90% of an entrepreneur’s tasks fall into the first two categories. Subagents are a next-level tool, for when you move from “one task at a time” to orchestration.

Where Do Subagents Live, and Which One Takes Precedence?#

The subagent hierarchy has five levels, ordered from highest to lowest priority:

The priority logic is the same as for Skills and CLAUDE.md: organization overrides CLI, CLI overrides project, project overrides personal, and personal overrides plugin.

What to Know About Loading

Subagents load when a Claude Code session starts. If you manually edit an agent file on disk, the changes will not be picked up until you restart the session. Edits through the interactive /agents UI apply immediately.

One subagent per scope means one file. If .claude/agents/ contains code-reviewer.md and another code-reviewer.md next to it (for example, from an old backup), Claude Code will silently ignore one of them. There will be no notification.

Plugin subagents are a separate matter. They have security restrictions: they do not support the hooks, mcpServers, and permissionMode fields. This prevents installing a third-party plugin from giving it permission to run arbitrary code on your machine.

How a Subagent File Is Structured: Frontmatter and Body#

A minimal example from the official documentation—just 9 lines:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

That is enough. If a user says “review my PR” in the main chat, Claude matches “reviewer / code / quality” with the description and delegates to the subagent. The subagent reads the diff, produces comments, and returns a summary to the main chat. The main chat does not get cluttered with logs and intermediate analysis.

Full Frontmatter Schema

The model: haiku field is exactly that “cost control” from the list of five goals. If you have a research agent that reads 50 pages of documentation, run it on Haiku to save 5–7 times compared with Opus.

The isolation: worktree field addresses an important problem: a subagent makes potentially dangerous changes (refactoring, migration), but you do not want it to touch your working copy. Set isolation: worktree, and Claude Code creates a temporary git copy of the project; the subagent works there and returns a diff for review.

The File Body Is the System Prompt

After the frontmatter comes ordinary Markdown—that is the subagent’s system prompt. No special structure is required, but this is a proven pattern:

1. Who you are — one sentence: “you are a code reviewer,” “you are a security auditor,” “you are a documentation maintainer.”
2. When you are invoked and what you do first — the first 2–3 actions after receiving the task.
3. A checklist of checks or steps — 5–10 points the subagent follows.
4. What you return — the final report format. This is critical: if you do not specify a format, the subagent will produce an “essay” instead of a structured summary.
5. What you do NOT do — explicit limitations. Without this section, the subagent slips into improvisation.

Keep the file body to 200–500 lines. If it gets longer, move lengthy references to separate nearby files and link to them in the prompt.

How to Write a Description So Claude Definitely Invokes Your Subagent#

A common pain point is setting up a subagent for code review, only to see Claude do everything itself without using the agent. There is usually one reason: the description is written as “Helper for code review.” Claude does not understand when to trigger it.

Formula for an Effective Description (3 Parts)

Part 1 — what it does. One sentence about the result, not the process. Not “analyzes code,” but “finds vulnerabilities in code and returns a list with severity and a fix.”

Part 2 — when to trigger it. 3–5 phrases in quotation marks, as users actually make requests. Do not guess—look at your chat history and real phrasing.

Part 3 — when NOT to trigger it. 1–2 phrases about similar tasks to which this subagent should not respond. Without this section, two similar agents constantly conflict.

The Magic Phrase “Use Proactively”

Anthropic’s official documentation makes a direct recommendation:

In other words, Claude is inclined not to invoke a subagent by default if the description has no clear signals. Add “use proactively” or “use immediately after writing code,” and activation rises sharply.

A Strong Description Looks Like This

description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code. Returns prioritized list of issues with severity
  and fix recommendations.
  Do not invoke for documentation changes, README edits, or commit
  message rewrites - these are handled by doc-maintainer.

What works here:

• The verbs “reviews” + “returns” specify a concrete result, not a process.
• “Proactively” and “immediately after” are explicit triggers.
• “Do not invoke for...” closes off conflict with a similar subagent.
• English in the description is standard. Claude matches better in English.

5 Ready-to-Use Subagent Roles That Work in 10 Minutes#

Each role below is a single file, .claude/agents/<name>.md. After creating the file, restart Claude Code, open /agents, and check that the new agent appears in the list. Then you can invoke it with @agent-name.

1. code-reviewer — review code after every change

This is the official example from Anthropic’s documentation, adapted for a work process:

---
name: code-reviewer
description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code.
tools: Read, Grep, Glob
model: inherit
color: blue
---

You are a senior code reviewer ensuring high standards of code quality.

When invoked:
1. Read the diff and changed-file list supplied by the main session. If missing, ask the main session to provide them.
2. Use Read, Grep, and Glob to inspect the relevant files.
3. Return findings without changing files or running shell commands.

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Test coverage adequate
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix.

The key is tools: Read, Grep, Glob: the reviewer has file-reading and search tools, with no Bash, Write, or Edit access. The main session prepares the diff and passes it to the reviewer. Merely instructing an agent to run only git diff would not restrict a fully granted Bash tool.

2. security-auditor — find vulnerabilities and leaks

This role uses opus for deeper reasoning and the same Read, Grep, and Glob tool restriction. Persistent memory is omitted from this read-only template because enabling agent memory also gives it memory-writing capability:

---
name: security-auditor
description: |
  Security audit specialist. Use proactively to find OWASP Top 10
  vulnerabilities, exposed secrets, injection risks, broken auth.
  Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
color: red
---

You are a security auditor. Find exploitable vulnerabilities, not style issues.

Audit checklist:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- CSRF / SSRF risks
- Hardcoded secrets (API keys, tokens, passwords)
- Broken auth / session management
- Insecure deserialization
- Missing input validation
- Path traversal
- Open redirects
- Insecure direct object references (IDOR)

For each finding:
- Severity: Critical / High / Medium / Low
- File:line
- Attack scenario in 1–2 sentences
- Fix recommendation with code example

Skip linter or style noise. Report only exploitable issues.

Read-only in terms of tools, with model: opus for complex checks such as vulnerability chains.

3. research-agent — deep research across 8+ sources

This pattern is described by Anthropic itself in its article about the multi-agent research system. The key is an explicit output format and a ban on dumping raw results:

---
name: research-agent
description: |
  Deep web research specialist. Use proactively for fact-finding,
  competitive analysis, gathering external documentation, comparing
  approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

You are a research analyst. Goal: synthesized brief, not raw search dumps.

Process:
1. Decompose the question into 3–5 sub-queries
2. WebSearch each sub-query, fetch top 3–5 sources per query
3. Cross-verify claims across at least 2 independent sources
4. Reject SEO-farm and aggregator content; prefer primary sources
5. Quote verbatim with URL attribution for any specific claim
6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum)

Anti-patterns to avoid:
- Don't cite a fact from a single source
- Don't paraphrase quotes as if they were verbatim
- Don't return raw search result dumps to the parent
- Don't include filler intro / outro ("Hope this helps")

maxTurns: 30 is a safeguard against research going into endless iterations. Anthropic reports this figure in its multi-agent system:

Ninety percent refers to research benchmark tasks. In practice, the gain is smaller for business tasks, but the general scale is similar.

4. doc-maintainer — keep documentation in sync with code

This role uses model: haiku—a typical example of “cost control.” Documentation does not require Opus; Haiku does the job for a third of the price:

---
name: doc-maintainer
description: |
  Documentation sync specialist. Use after merging features to update
  README, API docs, CHANGELOG. Reads recent commits, identifies
  undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

You maintain documentation in sync with code.

When invoked:
1. Run `git log --since="last release"` to see recent changes
2. Read README.md, docs/, CHANGELOG.md
3. Identify gaps: new features without docs, removed APIs still
   documented, version mismatches

Output:
- Updated files (use Edit, not Write - preserve existing structure)
- CHANGELOG.md entry in Keep-A-Changelog format
- List of changes you made (actual diff summary, not paraphrase)

Style rules:
- Active voice, present tense
- Code examples must be copy-pasteable
- No marketing language ("powerful", "robust", "seamless")
- No filler ("This guide will help you...")

5. refactor-agent — safe refactoring through a worktree

This role uses isolation: worktree—the subagent works in a separate copy of the repository, and you merge only if it is OK:

---
name: refactor-agent
description: |
  Safe refactor specialist. Use for renames, extracts, inlines that
  shouldn't touch your working copy until reviewed. Runs in a
  temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

You refactor code without changing behavior.

Strict rules:
1. Tests must pass BEFORE and AFTER the refactor.
   If pre-refactor tests fail, STOP and report.
2. One atomic refactor per commit (extract, rename, inline).
3. Never change public APIs without explicit instruction.
4. Never modify tests unless they test the refactored implementation
   directly.

Process:
- Run test suite -> baseline
- Make atomic refactor
- Run test suite -> verify
- Commit with conventional message: refactor(scope): what

Return: summary of changes + worktree path so user can diff and merge.

With this role, the most painful refactoring problem—“I broke it and don’t know how to roll back”—goes away: the original copy remains untouched, and the subagent works in an isolated worktree.

Launching 5 Subagents in Parallel: Orchestrator + Workers#

Parallel orchestration is a “conductor + orchestra” setup. The conductor holds the plan, does not write the notes, and checks what the musicians play. If someone hits a wrong note, the conductor asks them to play it again rather than trying to finish in their place.

For an entrepreneur, a closer analogy is a marketing agency preparing a strategy for a new client. One analyst does a SWOT, another conducts a competitor analysis, a third creates an audience profile, a senior analyst filters out hypotheses that do not fit the budget, and the project manager assembles the final presentation. In Claude Code, this pipeline starts with one sentence—and the critic is built into the process instead of arriving after the fact.

Minimal Orchestration Prompt

One sentence in the main chat is enough:

Launch five subagents in parallel: three research-agents on different sources
(Anthropic docs, GitHub repos, AI bloggers), one critic-agent to filter out
weak conclusions, and one summary-agent for the final document.

Context: I am writing a guide about X. Target length: 2,000 words with sources.
Before starting, each one reads CLAUDE.md.

Claude then delegates to the five agents. Each works in its own context: the research agents use their respective sources, the critic filters, and the summary agent assembles. Only final summaries return to the main chat.

Where Parallelism Pays Off

Not everywhere. Parallel execution only makes sense when:

1. Tasks are independent. If research-agent #2 is waiting for research-agent #1’s result, there will be no parallelism—they will effectively work sequentially.
2. Tasks take a long time. Parallelizing “trim trailing whitespace” is pointless; the overhead of launching subagents will eat up the gain.
3. You have enough limits. More on this in a separate section below—parallel subagents burn through tokens quickly.

Anthropic’s Multi-Agent v2: A Further Step

In May 2026, Anthropic released Multi-Agent Orchestration v2 with three important differences from the classic approach of launching parallel subagents. More on that in the next section.

What’s New in Multi-Agent v2: Orchestration, Outcomes, Dreaming#

Multi-Agent Orchestration: Shared Filesystem + Mid-Workflow Check-ins

Anthropic describes the feature this way:

The key difference from classic subagents is a shared filesystem. Before, each subagent worked in complete isolation, and exchange happened only through the returned summary. Now specialists can write to a shared folder, and the lead agent reads results as the work progresses, not just at the end. This solves the problem of “everyone worked all day, and at the end it turned out that two people had incompatible approaches.”

Second are mid-workflow check-ins. The lead agent can pause and ask any specialist “how’s it going,” then adjust the overall plan. This is close to how a real team manager works.

Outcomes: A Rubric Instead of Step-by-Step Instructions

With Outcomes, you write success criteria, and the agent finds a way to meet them. A separate grader checks the result in its own context so it is not “contaminated” by the main agent’s reasoning.

Ten percent on challenging tasks is a serious gain. Especially when a task is framed as “assemble a long-form article that meets these quality criteria,” rather than “follow steps 1–7.”

Dreaming: Agents Accumulate Experience Between Sessions

This is the most conceptually new feature. An agent goes through past sessions, finds patterns in successes and mistakes, and updates the memory store. You can configure manual review before applying changes, or let it edit memory itself.

Anthropic reports that a legal tech customer saw about a sixfold increase in success on legal-drafting tasks after implementing Dreaming. This is already working in production, not just in a demo.

What This Means for Entrepreneurs Who Don’t Program

Multi-Agent Orchestration is currently available through the Claude Agent SDK, not directly in the Claude Code CLI. But the direction is clear: orchestration is moving from “you manually launch N subagents” to “you describe the task, and the lead agent decides whom to delegate to and how.” If you are just starting with subagents, do not worry about v2 yet. Learn the classic pattern of “1 main chat + 3–5 subagents with different roles,” and in 3–6 months you can move naturally to Managed Agents.

7 Mistakes That Leave Subagents Dead in the Water#

Mistake 1. “Helper for X” Descriptions Don’t Trigger

Symptom: you wrote a subagent, checked the structure, and everything is valid, but Claude does not invoke it for user requests. The reason is almost always the same: the description is abstract, such as “Helper for code review.” The fix: write 3–5 real user phrases in quotation marks directly in the description, plus “use proactively” / “use immediately after.”

Mistake 2. Creating a Subagent Where a Skill Is Needed

A subagent costs more than a Skill—it creates its own context, loads its own system prompt, and uses more tokens. If a task is short, will not consume the main context, and can be done in one pass, it should be a Skill, not a subagent. An anti-pattern example: a format-validator subagent that checks a JSON schema against 20 rules. This should be a Skill: one model, no isolation needed, no extra context loaded.

Mistake 3. Launching “60 Parallel Agents” from the Start

This is the most widespread illusion. You see a tweet saying, “I have 1,500 agents working,” and think, “I should do that too.” In practice, 60 agents burn through a Pro plan’s limits in an hour, generate a pile of conflicting results, and at the end of the day you have nothing finished.

The fix: start with one subagent for one task. Once you have mastered that, add a second with a different role. Once you have mastered orchestrating two, move on to a team of 3–5. Jumping from “installed Claude Code yesterday” to “20 in parallel today” is guaranteed to break code and burn through limits.

Mistake 4. Giving Every Agent All Tools

If your code reviewer has access to Bash, Write, and WebFetch, that is a huge security and cost hole. A reviewer should not have permission to write files, much less access the internet.

The fix: strictly limit tools. A code reviewer gets only Read, Grep, Glob. A security auditor gets the same read/search tools and a diff supplied by the main session. Adding Bash grants shell capability; it does not automatically restrict the agent to git diff. A research agent gets WebFetch, WebSearch, Read, Write. Do not give a subagent more permissions than it needs for one specific task.

Mistake 5. A Subagent Dumps Raw Results into the Main Context

If a research agent returns “here are all 30 pages I found; figure it out yourself” to the main chat, you have lost the main advantage of subagents: noise isolation. The fix: explicitly require an output format in the subagent’s system prompt. “Return ONLY: 3-bullet TL;DR + 5-source list. NO code dumps, NO raw search results.” This format should be strict—the subagent should not have the freedom to “turn it into an essay.”

Mistake 6. Vague Invocations: Unclear Delegation Requests

A subagent cannot see the main dialogue’s history. It starts with a clean context + CLAUDE.md + whatever you explicitly wrote to it. If you write “fix authentication,” the subagent will make things up. Instead: “Fix the OAuth redirect loop where, after a successful login, the user gets redirected to /login instead of /dashboard. File: src/lib/auth.ts.”

A clear rule: when delegating, give the subagent as much context as you would give a new contractor who just joined the project.

Mistake 7. Role-Based Agents Instead of Task-Based Agents

A tempting pattern is: “let’s create a frontend-developer, backend-developer, and qa-engineer, and have them work as a team.” It does not work. Each “role” loses context about the whole project, and they cannot agree on details because they cannot see one another.

The fix: a subagent should handle a recurring task with a clear output, not a role. Not “frontend-developer,” but “explore-ui-tree,” “refactor-component,” “audit-accessibility.” Each task-based subagent does one specific job and returns one specific result.

How Much Do Parallel Subagents Cost, and When Do They Pay Off?#

A Pro plan will be exhausted within an hour if you launch 5 parallel subagents on complex tasks. Max 5x ($100) is a realistic minimum for regular parallel work. For teams and Enterprise, the question of money is already handled at the tooling-budget level.

For more on saving tokens in Claude Code, see the separate guide to limits. For subagents, the key rule is that a subagent pays off on a task requiring at least 10 minutes of focused work. If a task is shorter, do not create a subagent; do it in the main chat or with a Skill.

How Do You Integrate Subagents with CLAUDE.md, Skills, and a Second Brain?#

A subagent relies on three things that should be in your project before you create your first specialist:

1. The right CLAUDE.md. A subagent reads CLAUDE.md before starting—it is its “employment contract.” Without it, a subagent does not know the project context, its restrictions, or its tone. It will make things up.

2. Basic Skills. A Skill is a packaged methodology. A subagent loads only the Skills it needs, not everything at once. Without Skills, a subagent repeats the same work from scratch every time.

3. Second Brain: a knowledge structure. The business/ folder (or its equivalent in your field) is a library that all subagents consult. Without it, a subagent gives an average ChatGPT answer that is indistinguishable from anyone else’s.

Reversing this order means getting hype without results. “I have 60 parallel subagents” with an empty business/ folder means 60 average ChatGPT sessions with the same approach.

The fastest way to start is to copy code-reviewer from the first example above into .claude/agents/code-reviewer.md, restart Claude Code, and invoke @agent-code-reviewer on your next commit. In 5 minutes, you will know whether you need subagents or whether the main chat is enough.