Subagents Deep Dive
Specialized AI personalities with isolated context, scoped tools, and reusable definitions.
What a Subagent Is
A subagent is a preconfigured AI personality the main Claude Code agent can delegate work to. It has its own system prompt, its own context window separate from the main conversation, and its own scoped tool set. Subagents are reusable across projects and can be shared with a team via version control.
Defining a Subagent
Subagents are Markdown files with YAML frontmatter. Project-level subagents live in .claude/agents/, user-level in ~/.claude/agents/. The name and description fields are required; tools, model, and color are optional.
---
name: code-reviewer
description: Reviews diffs for security, performance, and convention violations. Invoke after any code modification.
tools: Read, Grep, Glob, Bash
model: sonnet
color: yellow
---
You are a senior code reviewer. For each finding, output:
- Location: file:line
- Severity: critical / warning / suggestion
- Issue: one-sentence summary
- Fix: concrete code snippet
Critical issues block merge.Use the /agents slash command to create subagents interactively. Claude generates the description, suggests tools, and walks you through model selection without writing the Markdown manually.
Invocation Patterns
| Pattern | How | When |
|---|---|---|
| Auto-delegate | Main agent matches description against user intent | Description has clear keyword triggers ("code review", "diagram") |
| Explicit @-mention | @code-reviewer review the staged diff | You want to force a specific subagent regardless of description match |
| Slash command | Subagent wrapped in a custom skill exposed as /command | Workflow that always uses the same subagent |
Why Context Isolation Matters
The main agent's context grows with every turn — file reads, tool outputs, conversation history. As context fills up, model performance degrades. Subagents fix this by running in a side chain: the main agent sends a single prompt, the subagent works in isolation with its own fresh context, and returns one condensed response. Only that response enters the main thread.
- ▸Main agent stays lean — no tool noise from subagent execution leaks back
- ▸Subagent gets focused context tailored to its specific task
- ▸Each subagent specializes — better results than the main agent doing everything
- ▸Reduces need for /compact or /clear because main context grows slowly
Tool Scoping and Least Privilege
Granting a subagent every tool is tool pollution. Each tool definition adds tokens to the subagent's context and grants capabilities it does not need. A diagram-generator only needs Write — not Bash. A code-reviewer only needs Read, Grep, Glob — not Edit. Scope tools to the minimum the task requires.
A subagent's description is appended to the main agent's system prompt. A malicious description from an untrusted source could manipulate the main agent into harmful behavior. Treat third-party subagents like any third-party dependency — review before installing.
Spawning Multiple Instances
Multiple instances of the same subagent can run for parallel work. Phrasing matters — Claude Code does not always assume tasks are independent. Saying "review this PR" runs sequentially. Saying "review these files in parallel" or "create separate review agents for each file" makes independence explicit and triggers concurrent execution.
# Sequential — Claude may run reviews one after another
> create 2 funny code reviews of @main.py
# Parallel — explicit independence triggers concurrent execution
> review these files in parallel: @auth.py @api.py @db.py
> create separate review agents for each file