The Description Field Is the Router: Writing Claude Code Subagents That Delegate Correctly

TL;DR: Claude routes to subagents purely by matching your prompt against each subagent's description field — bad descriptions miss delegations; nested spawning (v2.1.172+) lets a subagent fan out verifiers without ever touching your main context window.

How routing actually works

When Claude Code sees a task, it reads each loaded subagent's description field and decides whether to delegate. That's the entire routing mechanism — no magic, just text matching.

Bad description (misses delegations):

description: "Helps with code review."

Good description (routes correctly):

description: "Use after writing or modifying code files. Reviews diffs for correctness bugs, security issues, and style violations. Invoke with the list of changed files."

Include three things: when to invoke, what input to provide, and what the subagent returns. Claude reads this like a function signature.

Nested subagents: fan-out without polluting context

As of Claude Code v2.1.172, a subagent can spawn its own subagents. The canonical pattern: a reviewer reads a diff, produces findings, then dispatches a separate verifier per finding — only the top-level summary returns to your main session. All intermediate tool calls, logs, and reasoning stay inside the subagent's isolated context window.

Practical depth limit: 2–3 levels. Token costs compound and debugging gets opaque beyond that.

A concrete chain:

main session (Opus)
  └─ triage-lead subagent (Opus) — reads issue, routes to fix or investigate
       ├─ repro-runner subagent (Sonnet) — reproduces the bug
       └─ log-summarizer subagent (Haiku) — reads logs, returns structured summary

To prevent a subagent from spawning further:

{
  "tools": ["Read", "Edit", "Bash"],
  "disallowedTools": ["Agent"]
}

Cost and inheritance notes

• Point Explore-style research subagents at Haiku via the model field; save Opus for the main thread.
• Subagents do not inherit parent skills — list any required skills explicitly in the subagent's frontmatter.
• A subagent 5 levels deep cannot spawn further regardless of settings.

Sources: Subagents in the SDK — Claude Code docs · Anthropic's recommended subagent setup (XDA) · Claude Code nested subagents guide