Sub-agents in Claude Code (/agents)

A single agent drowns in a big task: context fills up, focus drifts away. Sub-agents turn Claude Code into a team of parallel specialists 🧩

What it is

Sub-agents are specialized child agents inside one Claude Code session: each has an isolated context window, a narrow system prompt, its own tool set and its own model. Technically it's just a Markdown file with a YAML front matter block in .claude/agents/ (per project) or ~/.claude/agents/ (across all your projects). The main orchestrator session hands out tasks and collects the summaries. The next step up is Agent Teams: several "teammate" sessions with a team lead and shared coordination.

Where it came from

• June 2025 - Anthropic described its multi-agent research system: an orchestrator plus parallel sub-agents.
• July 2025 - Claude Code v1.0.60: custom sub-agents and the /agents command appeared.
• Early 2026 - Agent Teams: an experimental feature behind the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 flag.
• Recently (v2.1.198) - sub-agents run in the background by default, and the interactive /agents wizard was removed: you now ask Claude itself to create a sub-agent, or write the file by hand. The file format hasn't changed.

Why it took off

• One agent drowns in a big task: context overflows, focus is lost. Sub-agents give you isolation and parallelism: the "noisy" work (code search, logs, tests) stays in their windows, and only the conclusion comes back to the main chat.
• A narrow role = less improvisation, and permissions are easy to restrict: the tools and permissionMode fields sit right in the file's front matter.
• Economics: routine goes to a fast cheap model (model: haiku), judgment goes to a top one.
• The config is portable: a file in .claude/agents/ gets committed to the repo - the "reviewer" works the same for the whole team.

How to apply it now

1. Create .claude/agents/code-reviewer.md (or ask Claude: "create a reviewer sub-agent in .claude/agents/"):

---
name: code-reviewer
description: Reviews code for quality and security. Use after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. Find concrete problems (security, readability,
performance) and propose targeted fixes.

Only name and description are required - Claude works out when to delegate from the description. 2. Parallelism starts with an ordinary sentence: "research the auth, db and api modules in parallel with separate sub-agents." Each digs in its own context and runs in the background (Ctrl+B sends a task to the background manually). 3. Need a specific agent guaranteed? @-mention it: @agent-code-reviewer take a look at the changes in auth. 4. Fine-tuning lives in the same YAML front matter: memory (persistent agent memory across sessions), isolation: worktree (edits in a separate git worktree), mcpServers, hooks, maxTurns.

What to watch out for

• Coordination costs tokens: for small stuff one agent is cheaper than an orchestra, and the docs honestly flag Agent Teams as noticeably more token-hungry - every teammate has its own context.
• Sub-agents don't see the session history or each other's context - connect them through explicit artifacts (a spec, a report, a file), not "from memory".
• All sub-agent results come back into the main window: a dozen chatty agents will clog your context just as badly as one raw log.
• Parallel edits to the same file = conflicts; separate their areas of responsibility or turn on isolation: worktree.
• Nesting exists (a sub-agent can spawn its own, since v2.1.172), but no deeper than 5 levels.
• The /agents command no longer opens a menu wizard in recent versions - don't go looking for it, ask Claude or edit the files.

🤖 Prompt accelerator

"Create three sub-agents in .claude/agents/: 1) researcher - read-only (tools: Read, Grep, Glob; model: haiku), explores the codebase and returns a short report; 2) test-writer - writes tests based on the researcher's report; 3) code-reviewer - read-only review of the diff against a security/readability/performance checklist. Give each a short system prompt for its role. Then take this task : run researcher in parallel across the modules , apply fixes based on their reports, then run test-writer and code-reviewer. Return only summaries to the main chat."