Anthropic's own production multi-agent research system spent roughly 15× more tokens than chat and outperformed single-agent Claude Opus 4 by 90.2% on their internal research evaluation (Anthropic, 2025). That ratio is the entire conversation about orchestration in two numbers. You can buy a 90% lift, but only if you're willing to pay 15× per task and only if your workload actually justifies it.
I've been shipping Claude Code workflows for a year, and the question I get asked most often isn't "how do I build agents." It's "do I need a subagent here, or a skill, or an agent team?" People reach for the wrong abstraction, watch the bill triple, then conclude multi-agent systems don't work. That's not what's happening. They're picking the wrong primitive for the problem.
This is a working operator's guide. What each abstraction actually does, when to reach for which, the code patterns that survive production, and the failure modes nobody warns you about until you're three quarters into your token budget.
Key Takeaways
- Anthropic's own multi-agent system used ~15× more tokens than chat and improved research-task performance by 90.2% versus single-agent Opus 4 (Anthropic, 2025).
- Skills load only ~100 tokens of metadata until invoked, making them the cheapest abstraction for repeatable procedures (Anthropic, 2025).
- The Berkeley MAST study identified 14 distinct multi-agent failure modes across 1,642 traces, with inter-agent misalignment accounting for 32.3% of all failures (Cemri et al., NeurIPS 2025).
- Anthropic's framing for the split: "MCP connects Claude to data; Skills teach Claude what to do with that data" (Anthropic, 2025).
What Are Claude Code Subagents, Skills, and Agent Teams?
The three abstractions answer three different questions. Subagents answer "who does this task?" Skills answer "how should this task be done?" Agent teams answer "how do multiple workers coordinate when one isn't enough?" Anthropic's own framing in the Skills explainer draws the first line clearly: "MCP connects Claude to data; Skills teach Claude what to do with that data," while subagents are described separately as "self-contained agents designed for specific purposes that handle workflows independently" (Anthropic, 2025). Pick the wrong one and you'll feel it in latency, tokens, or both.
A subagent is a separately-invoked Claude session with its own context window, system prompt, and tool allowlist. You define it once in .claude/agents/<name>.md, then the parent agent dispatches tasks to it via the Task tool. The subagent runs to completion and returns a summary. The parent never sees the subagent's working context, only the result. That isolation is the feature (Anthropic, 2025).
A skill is a packaged procedure: a SKILL.md file plus optional scripts and references that teach Claude how to do something specific. Skills use progressive disclosure. Only the description (~100 tokens of metadata) loads at session start. The full skill body loads only when Claude decides the description matches the current task (Anthropic, 2025). One skill, many invocations, low ambient cost.
An agent team is a set of full Claude Code sessions working together, with one acting as lead. Unlike subagents, "which run within a single session and can only report back to the main agent," teammates message each other directly and claim work off a shared task list (Anthropic, 2026). This became a native feature rather than an SDK pattern, but it's experimental and off by default. For teams that span more than one Claude Code session, you're still designing the harness yourself on the Claude Agent SDK (Anthropic, 2025).
The mental model I use: subagents are processes, skills are functions, and agent teams are the architecture diagram that connects them. Mixing those metaphors is where most production confusion starts.
deeper dive on context engineering principles that make these three abstractions work together
When Should You Use a Claude Code Subagent?
Reach for a subagent when you need context isolation. Anthropic's engineering team published that token usage alone explains 80% of performance variance on their BrowseComp eval (Anthropic, 2025), which is another way of saying that what's in the context window is the most important thing about an agent. Subagents are the only abstraction that gives the parent a clean wall between its own context and a task's working memory.
The canonical case is parallel research. You give five subagents five overlapping queries, they each burn through their own context windows fetching and reasoning, and the parent only sees the five summaries. Without subagents you'd cram all five queries' raw tool output into one context, hit the rot threshold, and watch quality collapse. The Chroma Research "Context Rot" study tested 18 frontier LLMs and found that on LongMemEval "the Claude models exhibit the most pronounced gap between focused and full prompt performance" (Chroma Research, 2025). Subagents are how you structurally avoid that cliff.
Subagent definition lives in .claude/agents/<name>.md:
---
name: blog-researcher
description: Use proactively when the writer needs current statistics, image
sources, or competitive content gaps. Returns structured findings only;
never edits files.
tools: WebSearch, WebFetch, Read, Grep
---
You are a research specialist. Your job is to find tier 1-3 sources for
specific claims and return them in a structured findings table.
Constraints:
- Never write or edit files. Read-only.
- Return statistics with: number, source name, URL, date, methodology.
- Verify all URLs return HTTP 200 before reporting.
The parent invokes it with a self-contained prompt because the subagent has zero conversation history. From the Claude Agent SDK in Python:
from claude_agent_sdk import query, ClaudeAgentOptions
async def dispatch():
async for message in query(
prompt="Find 8 sourced 2025-2026 stats on multi-agent reliability.",
options=ClaudeAgentOptions(
agents={"blog-researcher": researcher_definition},
permission_mode="acceptEdits",
),
):
print(message)
Where developers get burned: spawning subagents for tasks the parent could do in two tool calls. Anthropic's own engineering postmortem describes their early system spawning 50+ subagents for simple queries because the lead agent didn't have a clear policy on when to delegate (Anthropic, 2025). In my own use, dispatch adds a couple of seconds of startup before any useful work happens, and it burns the parent's tokens on writing the brief. Below a certain task complexity, single-agent is faster, cheaper, and equally reliable.
The rule I follow: dispatch a subagent when the task either (a) requires a context window I'd otherwise pollute, (b) can run in parallel with other independent work, or (c) needs a different tool allowlist than the parent. Anything else, do inline.
When Should You Use a Claude Skill?
Reach for a skill when the same procedure repeats across sessions. Skills are designed for this exact case. The progressive-disclosure mechanic loads only ~100 tokens of metadata at session start, and the full skill body loads only when Claude's matcher decides the user's intent fits the description (Anthropic, 2025). A subagent dispatch costs you a fresh context window every invocation. A skill costs you next-to-nothing until it's actually needed.
A skill lives in .claude/skills/<name>/SKILL.md (or globally in ~/.claude/skills/):
---
name: blog-write
description: Use when the user asks to "write a blog post", "draft article",
or "create blog content". Generates SEO-optimized articles with sourced
statistics, charts, and answer-first formatting.
---
# Blog Writer
## Phase 1: Topic Understanding
Clarify audience, primary keyword, and target word count.
## Phase 2: Research
Spawn the blog-researcher subagent with the topic. Require 8-12 sourced
2025-2026 statistics from tier 1-3 sources only.
## Phase 3: Outline
Use the question-format heading pattern. Each H2 opens with a 40-60 word
answer-first paragraph containing one statistic.
[Full procedure continues...]
Notice the bidirectional play: this skill invokes a subagent. Skills and subagents compose. The skill knows the procedure (which agents to dispatch, in which order, with what brief). The subagent does the heavy independent work. When I rebuilt my own blog-writing workflow this way, the cost-per-article dropped roughly 40% because the skill metadata stays cheap and the expensive context-isolated work only fires when needed.
The Rakuten team reportedly saw an 87.5% time reduction on a relevant workflow after migrating to Claude Skills, though this number traces to a third-party report (Echofold, 2025) and should be treated as directional rather than canonical. The mechanism, regardless of the exact percentage, is the same: skills replace ad-hoc prompt repetition with a versioned, discoverable procedure.
Where skills fail: when the description field collides with another skill's description. Anthropic's authoring guide is blunt about the stakes, noting the description "is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills" (Anthropic, 2025). When a skill fires on the wrong request, the documented remedy is to make the description more specific (Anthropic, 2025). Tight, mutually-exclusive descriptions are not optional.
The rule: skill it when the procedure is a repeatable recipe (write a blog post, generate an SVG chart, run a security audit). Don't skill it when the work is one-off, exploratory, or needs the parent's full conversation context to make sense.
walkthrough of a real multi-agent code review skill with 9 specialized sub-skills
When Should You Use an Agent Team?
Reach for an agent team when the workers need to talk to each other, not just report back. That one distinction does more decision-making work than any other line in this article.
This is where most writing on the subject is out of date, including an earlier draft of this one. Agent teams used to be something you built yourself on the Claude Agent SDK. They're now a native Claude Code feature, though a gated one: you turn them on by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings or your environment, and without that variable "no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates" (Anthropic, 2026).
Anthropic publishes its own comparison, and it's sharper than the one I used to give:
| Subagents | Agent teams | |
|---|---|---|
| Context | Own context window; results return to the caller | Own context window; fully independent |
| Communication | Report results back to the main agent only | Teammates message each other directly |
| Coordination | Main agent manages all work | Shared task list with self-coordination |
| Best for | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
| Token cost | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
Source: Anthropic, 2026.
The mechanics matter here. A team lead spawns teammates, each teammate is a full independent Claude Code session with its own context window, and they coordinate through a shared task list plus a mailbox at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Task claiming uses file locking so two teammates can't grab the same work. You can also message any teammate directly instead of routing everything through the lead, which is the thing subagents genuinely cannot do.
You don't have to redefine your workers, either. A teammate can reference an existing subagent type, and it honors that definition's tools allowlist and model, with the definition's body appended to the teammate's system prompt rather than replacing it. Define security-reviewer once, use it both ways.
The honest caveats, because this is still experimental: teammates cannot spawn their own teammates, /resume and /rewind don't restore in-process teammates, there's exactly one team per session, and teammates sometimes fail to mark tasks complete, which blocks anything depending on them. Anthropic's own guidance is to start with 3-5 teammates and around 5-6 tasks each.
The code-review case is the canonical one, and it's now a prompt rather than a harness:
Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
If your team needs to run outside a single Claude Code session, the SDK route still applies, and Anthropic's framing there is that you design the harness yourself (Anthropic, 2025). A pragmatic orchestrator-worker pattern in Python:
from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio
REVIEWERS = ["security", "performance", "patterns", "tests"]
async def review_pr(pr_diff: str) -> dict:
"""Fan out to 4 specialist subagents, aggregate findings."""
tasks = [
query(
prompt=f"Review this diff for {dimension} issues:\n\n{pr_diff}",
options=ClaudeAgentOptions(
agents={f"{dimension}-reviewer": load_reviewer(dimension)},
max_turns=8,
),
)
for dimension in REVIEWERS
]
results = await asyncio.gather(*tasks, return_exceptions=True)
findings = {}
for dim, result in zip(REVIEWERS, results):
if isinstance(result, Exception):
findings[dim] = {"error": str(result), "issues": []}
else:
findings[dim] = parse_findings(result)
return aggregate(findings)
The two failure modes that consistently bite agent teams are state loss across handoffs and context contamination on aggregation. The Berkeley MAST taxonomy catalogued these explicitly. Six of their 14 documented failure modes (FM-2.1 through FM-2.6) are inter-agent misalignment failures: conversation reset, failure to ask for clarification, task derailment, information withholding, ignored input, and reasoning-action mismatch (Cemri et al., NeurIPS 2025). Inter-agent misalignment accounts for 32.3% of all observed multi-agent failures, second only to system design issues at 44.2%. That's not edge-case territory.
Source: Cemri et al., MAST taxonomy, NeurIPS 2025 Datasets and Benchmarks Track.
The mitigation is unglamorous. Write explicit briefs for each subagent. Validate their output before aggregation. Add a final verifier subagent whose only job is "did the team actually answer the question." Skip any of those and the chain dies quietly under load.
full anatomy of multi-agent failure modes and the production tells that surface them
When a chain does die quietly, the subagent's own transcript is often the only forensic trail you have: where Claude Code saves those sidechain JSONL transcripts and how to grep them after the fact.
Which Claude Code Orchestration Pattern Should You Pick?
Here's the decision matrix I use. Print it and tape it next to your monitor:
| Question | Use a Subagent | Use a Skill | Use an Agent Team |
|---|---|---|---|
| Is the work repeatable across sessions? | No, ad-hoc | Yes, same recipe each time | No, but the roles are |
| Does it need context isolation? | Yes, fresh window | No, runs in parent | Yes, one window per teammate |
| Do the workers need to talk to each other? | No, they only report back | N/A, no workers | Yes, this is the deciding question |
| Is parallelism beneficial? | Yes, fan-out N tasks | No, sequential procedure | Yes, parallel specialists |
| Token cost profile | One fresh window per dispatch | ~100 tokens metadata until needed | N full sessions, scales linearly |
| Best for | Research, analysis, audits | Writing, formatting, reviews | Competing hypotheses, cross-layer changes |
| Failure surface | Cost blowup on naive fan-out | Wrong skill matched, or description truncated out of the listing | Inter-agent misalignment; stuck tasks blocking dependents |
| Where it lives | .claude/agents/<name>.md |
.claude/skills/<name>/SKILL.md |
Native, behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
Three follow-up rules turn the matrix into a decision in under thirty seconds.
Rule 1: Default to skills. They're the cheapest abstraction by an order of magnitude. If your task is "do this thing the same way every time," it's a skill. Period.
Rule 2: Add subagents only when context isolation pays for itself. If you'd otherwise paste 50K tokens of tool output into the parent, dispatch a subagent. If you wouldn't, don't. Anthropic's own data: token usage explains 80% of performance variance (Anthropic, 2025). Protect the parent's context budget.
Rule 3: Reach for an agent team only when the workers benefit from arguing with each other. Competing-hypothesis debugging qualifies, because teammates actively try to disprove each other and the surviving theory is usually the real root cause. Parallel code review qualifies. "Write a blog post" doesn't, even though it has multiple steps, because the steps are sequential and share state. If nobody needs to hear what anyone else found, you wanted subagents.
Source: Anthropic engineering, multi-agent research system, 2025.
What Failure Modes Nobody Warns You About?
Three failure modes burn most teams in production, and none of them show up in the marketing material.
Skill collisions on progressive disclosure. Skills load based on a fuzzy match between user intent and the skill's description field. If two skills have overlapping descriptions, Claude can load the wrong one with no error signal. The output looks plausible but follows the wrong procedure. There's a second, less obvious version of this that bites once your library grows: Claude Code loads a listing of every skill's name and description into context, and when that listing exceeds its budget (1% of the model's context window by default), descriptions get truncated, which "can strip the keywords Claude needs to match your request" (Anthropic, 2025). Your skill doesn't collide, it silently stops being findable. Mitigation: write descriptions as if the matcher were adversarial, put the key use case first, and run /doctor to see what the listing actually costs.
Context contamination on aggregation. Subagents return summaries to the parent. If you let the parent dump those summaries verbatim into its own context, you reintroduce the rot you spawned subagents to avoid. The Chroma Research finding that even a single distractor in context drops accuracy below the no-distractor baseline is the empirical version of "summaries aren't free" (Chroma Research, 2025). Mitigation: have the parent ask each subagent for a structured payload (JSON, table, fixed schema) and store the working summaries in a side channel, not the parent's context.
Cost blowups from recursive dispatch. A subagent can dispatch another subagent. Without explicit limits, an ambiguous prompt can fan out exponentially. Every vendor has landed on some form of throttle here: OpenAI's Codex documents agents.max_concurrent_threads_per_session to "cap concurrently open spawned-agent threads, excluding the primary" (OpenAI, 2026), and Anthropic's own retrospective describes their early lead agent "spawning 50 subagents for simple queries" before they added budget controls (Anthropic, 2025). Note that a concurrency cap is not a depth cap. Nothing stops a chain from going three levels deep one agent at a time, so mitigation is on you: hard caps on subagent depth, dispatch count, and per-task token budget. Make the parent log every dispatch.
The pattern across all three failures: the orchestration layer has too few guardrails, not too many. Production multi-agent systems look "minimal" on the dispatch side but are heavily instrumented on the budget, schema, and validation sides. That asymmetry is the whole game.
why explicit evals are the only honest way to catch these failures before they ship
Which Production Patterns Actually Work?
Three patterns survive contact with production load. Use them, audit them, version them.
Pattern 1: Skill-with-subagent fan-out. A user-facing skill defines the procedure. The skill dispatches N specialist subagents in parallel, each with a tight brief and a strict tool allowlist. The skill aggregates structured outputs. This is what code review, blog writing, and most "do a complex thing well" workflows look like in practice. Anthropic's parallel-tool-call data shows this pattern can cut research time by up to 90% on complex queries (Anthropic, 2025).
Pattern 2: Skill-only with tools. No subagents. The skill defines the procedure and calls tools (MCP servers, scripts, file edits) directly within the parent context. This is the right pattern when the procedure is sequential, the context budget is small, and parallelism wouldn't help. Most lint, format, and refactor workflows are this.
Pattern 3: Agent team with verifier. A coordinator dispatches specialist subagents, then dispatches a separate verifier subagent whose entire context is "did the team actually answer the question, and is the output coherent?" This is the pattern that reliably defeats the inter-agent misalignment failure class. It costs an extra subagent dispatch. It saves you from shipping wrong answers at scale.
end-to-end walkthrough of building a Claude Code workflow that combines all three patterns
Frequently Asked Questions
Can a Claude Code subagent invoke another subagent?
Yes, but you need explicit depth controls. Without them, ambiguous prompts cause exponential fan-out. Anthropic's engineering team described their own system spawning 50+ subagents for trivial queries before they added budget controls (Anthropic, 2025). Cap subagent depth at 1 unless the workflow specifically requires deeper recursion, and instrument every dispatch.
How are Claude Skills different from MCP servers?
Skills teach procedures; MCP servers provide data access. Anthropic's framing is unambiguous on this: "MCP connects Claude to data; Skills teach Claude what to do with that data" (Anthropic, 2025). A skill encodes "how to write a blog post"; an MCP server encodes "how to talk to Postgres." They compose freely, a skill can call MCP tools.
When does a multi-agent system pay for its 15× token cost?
When the task either requires context isolation that single-agent can't provide, or benefits from genuine parallelism. Anthropic's evaluation showed multi-agent (Opus 4 lead with Sonnet 4 subagents) outperformed single-agent Opus 4 by 90.2% on research tasks (Anthropic, 2025). For simpler tasks, the lift is much smaller and rarely worth the multiplier.
Do agent teams need the A2A protocol?
Only if your team spans organizational or vendor boundaries. When the Agent2Agent (A2A) protocol moved to the Linux Foundation in June 2025, it did so with "more than 100 leading technology companies" behind it, Google, Microsoft, and AWS among them (Linux Foundation, 2025). Inside a single Claude Code session, native dispatch is sufficient and lower-overhead.
What's the simplest way to start using subagents?
Pick one repeatable workflow you currently do inline that pollutes your context (research, large-file reads, exploratory greps). Define a single subagent in .claude/agents/<name>.md for it, give it a tight tool allowlist, and let your skill or the parent dispatch it. Measure the context-window delta. That single change usually justifies the abstraction without any further investment.
MCP and A2A protocol architecture details for cross-system agent collaboration
Conclusion
The three abstractions answer three different questions, and the cost climbs steeply as you move up the stack. Skills are the cheapest tool for repeatable procedures. Subagents are the right tool for context isolation and parallel independent work. Agent teams are the right shape only when the workers need to talk to each other, and you should expect to pay for a full Claude session per teammate to get that.
The teams I see ship reliable multi-agent systems aren't the ones with the most sophisticated orchestration. They're the ones who picked the smallest abstraction that actually solved the problem, instrumented their budgets, and added a verifier subagent before they trusted the output. Start there.
And before you commit to a teammate-per-worker architecture, price it honestly against your plan: how Claude Code pricing and usage limits actually work across Pro and Max.
Top comments (0)