Claude Code Subagents: How to Build and Invoke Them (August 2026)

Summary: how do Claude Code subagents actually work in 2026?

• A subagent is one markdown file under .claude/agents/. Only name and description are required; the other thirteen fields are optional.
• The /agents panel that most 2025 tutorials tell you to open was removed in v2.1.198. You write the file yourself now, or ask Claude to write it.
• Subagents don't make Claude faster. They keep your main conversation from filling with grep output and logs. Delegate only work whose middle is much longer than its conclusion.
• The trap: a context-heavy task handed to a blank subagent goes slower, not faster — fork the conversation with /subtask instead. And a reviewer told to find gaps will find something even when the code is fine. The official docs warn about that directly.
• There are now four ways to parallelize (subagents, agent view, agent teams, dynamic workflows). The decision table below sorts them out.

Last updated 2026-08-25. Field names and versions follow the current docs at code.claude.com.

What breaks if you follow a 2025 tutorial

The syntax didn't just drift. The creation flow itself changed.

The model lineup turned over too: claude-opus-5, claude-sonnet-5, claude-fable-5, claude-haiku-4-5. Don't append a date suffix — claude-opus-5 is the complete ID.

Subagents solve exactly one problem

A subagent is not a CPU core. It doesn't do the same work twice as fast; it keeps garbage out of your main conversation. The official best-practices page opens by calling the context window the fundamental constraint on performance.

Ask your main session to "find every call site of this API" and half of it is now grep output. The refactor you actually wanted has nowhere to sit. Delegate the same instruction and the searching burns that context while your thread gets back a few lines. One test: if the intermediate work is much longer than the answer, delegate. Otherwise ask directly.

Where the files live

Definitions are markdown files, resolved in this order — higher wins:

1. Managed settings → 2. the --agents CLI flag → 3. .claude/agents/ (project, shared with the team) → 4. ~/.claude/agents/ (personal) → 5. agents/ shipped by a plugin.

Levels 3 and 4 are scanned recursively, so .claude/agents/review/security.md works. Put shared reviewers in the project; put taste-level checkers in your home directory.

Every frontmatter field

Required: name (lowercase and hyphens, no colons) and description. Automatic delegation reads that one sentence to decide, so a vague description means the agent never gets invoked.

The minimal example from the docs:

---
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.

With the 2026 fields, saved as .claude/agents/security-reviewer.md:

---
name: security-reviewer
description: >
  Reviews a diff for injection, authz, and secret-handling issues.
  Use after any change touching auth, DB queries, or external input.
tools: Read, Glob, Grep, Bash
model: opus
effort: high
isolation: worktree
memory: project
---

You review diffs for security defects only.

Report format:
- file:line — the problem — why it is dangerous — the smallest fix
If you find nothing, reply "no findings" and stop. Do not invent problems.

Narrowing tools to read-only isn't stylistic. Give a reviewer write access and it starts fixing instead of reviewing. Read-only reviewers and write-capable executors are the basic split.

Three ways to invoke one

Automatic delegation routes on description — convenient, not guaranteed. You can also name it in plain language: Use the test-runner subagent to fix failing tests. For a step that must run, use the @"code-reviewer (agent)" mention, which guarantees execution. To run a whole session as one agent, start with claude --agent code-reviewer.

Background items in the current session live under /tasks, workflows under /workflows. Don't reach for /agents to manage anything — the similarly named claude agents is a completely different feature.

Four patterns that pay off

Scoped investigation. Isolate "find everything related to billing" and take back only a file list and a summary.

Adversarial review. Never let the session that wrote the code grade it. Show the diff to a reviewer with a fresh context. The bundled /code-review skill has done this as a background subagent since week 30. Read failure mode 5 before you trust the output.

Forking with /subtask. A normal subagent starts blank; a /subtask fork inherits the entire conversation (tool calls and results stay isolated). Use it when you've spent an hour building context and want to peel off one branch. Fork mode became the default for interactive sessions in week 33; turn agent view off and the command becomes /fork while /subtask disappears.

/batch. Splits a large change across 5–30 subagents, each in its own worktree, each opening its own PR. Good for mechanical sweeps where every slice is independent.

Subagents vs agent view vs agent teams vs workflows

For scale: sixteen concurrent agents maximum, 1,000 per run. Exceed 25 agents or an estimated 1.5M tokens and you get a Large workflow warning. Inside a workflow script, import() and direct filesystem access are blocked, and there's no user input mid-run (v2.1.154+).

Sibling agents sharing a model, effort, tool set, schema, and working directory read each other's prompt cache — Claude Code holds the rest back for up to five seconds until the first response begins, specifically to force those hits. A practical reason not to make siblings gratuitously different.

Channels pushes external events into a running session. It isn't a parallelism mechanism, which is why it's absent from the table.

Common failure modes

Most of these come straight from the official warnings.

1. Unscoped "go investigate." Claude reads hundreds of files and burns the context. Narrow the scope or isolate it.
2. A subagent without enough context. Rather than writing a long briefing, fork with /subtask.
3. File collisions. Agent teams do not give you worktree isolation — split the files yourself. Subagents can use isolation: worktree.
4. Interrupting a fan-out is expensive. On resume, any agent that started after the incomplete one is re-run in full, even if it finished. Many small agents preserve more progress than one large one.
5. Trusting the reviewer too much. A reviewer asked to find gaps finds something even when the work is fine, and chasing all of it leads to over-engineering. Review output is input, not instruction.
6. Ignoring model selection. Every agent in a workflow inherits the session model. Check /model before a large run and pin light stages to a smaller model.
7. Delegating everything. If you can describe the resulting diff in one sentence, asking directly is faster. Delegation has fixed overhead.

What it costs

Running many subagents multiplies token consumption, and that lands on your plan limits. Parallelism isn't free speed — it's buying time with tokens. /usage breaks limit consumption down by skill, subagent, plugin, and MCP server (since week 21). Open it after one large run and you'll know which stage to demote to haiku next time.

Where to go next

For the theory behind the shape of all this, harness engineering lays out the five elements. If you'd rather manage several sessions from a Mac GUI, Conductor is the separate-app option.

One last thing: don't file CLAUDE.md and subagents in the same drawer. CLAUDE.md loads on every session; skills and subagents load only when needed. That's why CLAUDE.md has to stay short while a subagent definition can run long. Placement and merge order are covered in the CLAUDE.md guide.

Sources

• Anthropic Claude Code subagents documentation