Claude Code Subagents: The Complete 2026 Guide to Agent Teams

For two years, every AI coding agent shared the same shape: one long conversation, one growing context window, one tool surface. By the time you had a real project loaded, the model was working with half-truths and stale memory. Claude Code's 2026 subagents break that. Each subagent gets its own context window, its own system prompt, its own tool access, and the parent agent orchestrates them in parallel.

The result is the first time agentic coding actually feels like having a team. Not "one assistant who can do everything badly," but a stack of specialists who hand off work cleanly.

What changes when you compose agents

The old loop was sequential: explain a task, wait for the model to implement, ask it to write tests, ask it to review, ask it to ship. Every step accumulated context and slowed the model. A 500-file refactor would chew through 800K tokens before producing a PR.

With subagents, the parent spawns isolated children, each loaded only with the files and skills relevant to its job. The implementer never sees the test framework. The reviewer never sees the deployment pipeline. Each one is fast because each one is small.

Anatomy of a subagent

A subagent is defined by four things: a name, a system prompt, a tool allowlist, and an optional skill loadout. The parent invokes it with a focused task and gets back a structured result.

---
name: test-writer
description: Writes idiomatic tests for a specified file or feature.
tools:
  - Read
  - Edit
  - Bash
skills:
  - unit-test
  - integration-test
---

You write tests, only tests. You do not edit production code. You do not
explain. You read the target file, write a complete test file, run it,
and report pass/fail with the diff.

The three context layers

Every subagent invocation has three layers of context, in order:

1. System prompt: the subagent's instructions, declared in the agent file.
2. Skills: any SKILL.md files in the subagent's skills: list get inlined.
3. Task: the parent agent's specific request, including any file paths or arguments.

Nothing else. The parent's history doesn't leak in. Other subagents' outputs don't leak in. This is the single biggest behavioral difference from 2025-era agents.

The four canonical patterns

Most production agent teams compose one of four patterns. Knowing which one fits saves a lot of debugging.

1. Fan-out / fan-in

Parent spawns N parallel subagents, waits for all, merges results. The textbook use case is multi-file analysis: spawn oneanalyzer per directory, gather findings, deduplicate, report. Cuts a 12-minute serial scan to 90 seconds.

2. Pipeline (assembly line)

Sequential, but each stage is an isolated subagent.spec →implement →test →review →ship. Each one has fresh context, which is how you avoid the implementer rationalizing its choices when the reviewer pushes back.

3. Specialist + critic

Two subagents running tightly coupled: one produces work, the other critiques it. The parent forces a fixed number of rounds. Useful for high-stakes work like security audits and migrations where you want adversarial review built in.

4. Sandbox-then-merge

Subagent runs in a git worktree (Claude Code natively supports this in 2026). Parent reviews the diff before merging back. The subagent can fail catastrophically without touching the main branch.

A real ship-it pipeline

Here's the actual pipeline we use to ship features on skills-hub.ai. Every step is a subagent loaded from a SKILL.md file on the registry.

---
name: ship-it
description: End-to-end feature shipping. Spec → implement → test → review → PR.
subagents:
  - spec-writer
  - implementer
  - test-writer
  - code-reviewer
  - pr-author
parallel: [test-writer, code-reviewer]
---

Read the feature brief from $1. Spawn spec-writer to produce a
specification. Hand the spec + the codebase to implementer. When
implementer reports done, fan out test-writer and code-reviewer in
parallel against the diff. When both pass, hand to pr-author for the
PR body and submit.

If any subagent fails its acceptance criteria, halt and surface the
failure with the subagent's transcript. Do not auto-retry.

The parallel fan-out on test-writerand code-reviewer is the performance lever, they don't depend on each other, so running them serially is leaving 40% wall-clock on the table.

Compositions on skills-hub.ai

On skills-hub.ai, agent teams ship as composition skills, a SKILL.md file with asubagents: list in the frontmatter. Installing one pulls every child skill automatically.

# install a complete ship-it pipeline (one composition + 5 child skills)
npx @skills-hub-ai/cli install ship-it

# the CLI also wires the agent file under .claude/agents/
# so the pipeline is immediately invokable as /ship-it

Browse all compositions at /browse?category=combo or read more about the pattern in our agent teams guide.

Common mistakes (we hit all of these)

Treating subagents like functions

A subagent is not a function. It's a model invocation with a context window. Don't fan out 50 subagents in parallel, you'll hit rate limits and the parent will spend half its tokens just orchestrating. Cap at 3-5 concurrent for most pipelines.

Forgetting that the parent doesn't see subagent context

When a subagent reports back, the parent only sees what was returned, not the subagent's full transcript. If you want the parent to reason about how the work was done, the subagent has to summarize. Otherwise the parent will redo analysis the child already did.

Skipping the acceptance criteria

The biggest debugging cost in subagent pipelines is "the implementer said done but the work isn't done." Every subagent should declare explicit acceptance criteria in its system prompt: "You are done when: (a) tests pass, (b) lint passes, (c) the spec's checklist is all checked."

What's next

The interesting frontier isn't subagents themselves, they're shipped and stable. It's the composition layer: skill marketplaces that distribute subagent pipelines, tooling that visualizes the fan-out tree, and conventions for handing structured artifacts between stages.

If you're new to this, install one composition from skills-hub.ai and watch it run. You'll get the pattern in fifteen minutes, faster than reading another guide.

npx @skills-hub-ai/cli install ship-it

Related reading: the agent teams pattern guide, "subagent" in our glossary, and the Claude Code vs Antigravity 2.0 comparison if you're choosing between multi-agent platforms.