Subagents
What Claude Code subagents are, why they help at scale, and how to define and invoke them.
Subagents are specialized assistants inside Claude Code: each one gets its own context, a focused system prompt, and (optionally) a narrower tool list. The main session delegates work to them; they explore, run commands, or research, then return a compact result so your primary thread is not flooded with raw file dumps and search noise.
Use them when the same kind of side task keeps repeating (reviews, broad codebase searches, test runs) or when you want guardrails (for example read-only exploration) without re-typing instructions every time.
Built-in vs custom
Claude Code ships built-in subagents: Explore for read-only codebase search, Plan for research in plan mode, general-purpose for heavier multi-step work, and additional specialists such as Bash and statusline-setup. Those are chosen automatically when the task fits. Explore now inherits the main conversation’s model (capped at Opus on the Claude API); since v2.1.198 it no longer always runs on Haiku.
Custom subagents add your own behavior: you define when they apply (via a clear description) and how they behave (prompt, tools, model, and other options). For the full configuration reference and examples, see Anthropic's guide: Create custom subagents.
Defining custom subagents
Typical approaches:
- Markdown files with YAML frontmatter, usually under
.claude/agents/(project) or~/.claude/agents/(personal, all projects). - Ask Claude to create or update a subagent, or edit the Markdown files directly.
/agentsprints a reminder to use those flows. The old interactive creation library was removed in Claude Code v2.1.198.- CLI JSON with
--agentsfor one session (automation scripts, quick experiments); definitions are not persisted unless you also write files. claude agentsopens the background-session manager; it does not replace the removed subagent-definition library.
On Windows, claude ... invocations are the same in PowerShell and cmd as on macOS/Linux (see Overview: Shell commands).
Claude matches tasks to agents using each subagent's description. Invest time there: a precise "use when…" description improves automatic delegation.
How invocation works
You can combine these patterns:
Automatic delegation: describe the task normally; if it matches a subagent's description, Claude may spawn that subagent via the Agent tool and merge the result back into the main conversation.
Explicit natural language: ask directly: Use the code-reviewer subagent to… so the right worker is chosen for this job.
@ mention: type @ and pick the subagent from the typeahead (same idea as @ for files). That targets a specific subagent for the task instead of leaving the choice implicit.
Whole session as one agent: start with claude --agent <name> so the main thread uses that subagent's prompt, tool restrictions, and model for the session (see the official docs for details and implications).
For SDK / automation, programmatic clients define an agents map and include the Agent tool in allowed tools so the model can delegate; see Subagents in the SDK.
Example prompts
Replace agent names with ones you defined (or pick a built-in from the @ menu).
Explicit delegation:
Use the code-reviewer subagent on my last commit: P0/P1 only, correctness and security, not formatting. End with a short merge recommendation.Route via @ so the right worker runs:
@code-reviewer
Read-only pass on `src/payments/`: list trust-boundary risks (authz, amounts, idempotency). No code changes yet, table with file and concern.Exploration without flooding the main thread:
Delegate to Explore (or your explore-style agent): map every place we validate HTTP input before it hits the service layer. Return a compact table: route or handler, validator, gap if any.