CONCEPT Automatic delegation, driven by the description
Most of the time you don't invoke a subagent at all — Claude delegates automatically.
It decides based on the task description in your request, the description field
in the subagent's configuration, and the current context. When a task matches a subagent's description, Claude
hands it off. This is why a clear, detailed description matters so much: it's the signal
Claude uses to route work.
description field — e.g. "Expert code reviewer. Use proactively after code changes."CONCEPT Explicit invocation, when automatic isn't enough
When you want to control which subagent runs, three patterns escalate from a hint to a session-wide default:
| Pattern | How | Guarantee |
|---|---|---|
| Natural language | Name the subagent in your prompt: "Use the test-runner subagent to fix failing tests." | Claude still decides whether to delegate |
| @-mention | Type @ and pick it from the typeahead (or @agent-<name>) | Guarantees that specific subagent runs for the task |
| Session-wide | claude --agent <name>, or set "agent" in .claude/settings.json | The whole session runs as that subagent (its prompt, tools, model) |
With an @-mention, your full message still goes to Claude, which writes the subagent's task prompt from
what you asked — the mention controls which subagent is invoked, not the exact prompt it receives.
With --agent, the subagent's system prompt replaces the default Claude Code system prompt
for the whole session.
description. Explicit escalates: natural
language (a suggestion) → @-mention (guaranteed for one task) → --agent (the whole session).DIAGRAM How a subagent gets picked
@-mention a subagent?"} EXPL -->|"@-mention"| GUAR["🟢 That subagent runs
(guaranteed)"] EXPL -->|"natural language name"| SUG["Claude usually delegates
to the named one"] EXPL -->|"no"| AUTO{"Task matches a
subagent description?"} AUTO -->|"yes"| DEL["🟢 Auto-delegate"] AUTO -->|"no"| SELF["Handled in main conversation"] SESS["claude --agent NAME /
agent setting"] -.->|"whole session"| GUAR classDef ok fill:#d4edda,stroke:#28a745,color:#155724; class GUAR ok; class DEL ok;
CODE The three explicit patterns
Same subagent, three levels of control.
# 1. Natural language — Claude decides whether to delegate Use the code-reviewer subagent to look at my recent changes # 2. @-mention — guarantees THIS subagent runs for the task @"code-reviewer (agent)" look at the auth changes # 3. Session-wide — the whole session runs as this subagent $ claude --agent code-reviewer
// or make it the default for every session in a project: // .claude/settings.json { "agent": "code-reviewer" }
--agent CLI flag overrides the agent setting if both are
present.TRADE-OFFS Let Claude choose vs. force a subagent
✅ Automatic delegation
- Zero friction — no special syntax to remember
- Claude routes based on the best-matching description
- "use proactively" nudges it toward eager delegation
⚠️ Explicit invocation
- Deterministic: @-mention guarantees the exact agent
--agentreshapes the whole session — powerful but broad- More to type / configure; you own the routing decision
EXAM TRAPS
description. Explicit invocation is for when
automatic isn't enough.description field that drives automatic delegation. The body is the agent's system prompt,
used once it's running.--agent just adds a subagent you can call." → It runs the
entire session as that agent, replacing the default system prompt with the agent's and applying its
tools and model.PRACTICE
Q1 · What does Claude use to decide whether to auto-delegate to a subagent?
The task in your request, the subagent's description field, and the current
context. A clear description is what makes automatic delegation work — add "use proactively" to encourage it.
Q2 · You want to guarantee a specific subagent handles one task. How?
@-mention it (pick from the typeahead, or type @agent-<name>). That
forces that subagent to run rather than leaving the choice to Claude.
Q3 · What's the difference between naming a subagent in text and claude --agent name?
Naming it in text is a per-task suggestion Claude may act on. --agent runs the
whole session as that subagent — its system prompt replaces the default one, and its tool restrictions
and model apply for the session.