Subagent
A subagent is a specialist agent a primary agent delegates to — running in its own context window with its own prompt and tools, returning only a summary.
A subagent is an agent invoked by another agent: a specialist with its own context window, system prompt, and (usually restricted) toolset, which does a delegated job and returns a clean summary to its parent.
The mechanism buys three things a single thread can't. Isolation — a log-trawling investigation burns tokens in the subagent's context, not yours. Specialization — a focused prompt ("you review diffs for security issues; nothing else") outperforms a generalist on its niche. Safety — a reviewer with read-only tools physically can't edit code. Those properties make subagents the building block of every multi-agent pattern: fan-out, pipelines, orchestrator-worker, and fresh-eyes critics.
In Claude Code they're first-class and file-defined — a Markdown file whose description doubles as the delegation router (getting started, writing a good one) — and the hub's agents directory is a library of ready-made ones. The discipline that keeps them useful: one nameable job per agent, and remember they start blank — every constraint must be passed in, because a subagent sees nothing of the parent's conversation.
Frequently asked questions
- Why use a subagent instead of one bigger prompt?
- Context isolation. The subagent's noisy work — reading forty files, running a test suite — happens in its own window, and only the distilled result returns to the parent. The main conversation stays sharp, the specialist gets a focused system prompt, and a restricted toolset makes it safer than widening the main agent.
- How do subagents work in Claude Code?
- Each is a Markdown file in .claude/agents/ (or ~/.claude/agents/): frontmatter with a name, a description that acts as the routing signal, optional model and tools restrictions, then a system-prompt body. Claude delegates automatically when a task matches the description, or you invoke one by name in plain language.
Related
- Getting Started with Claude Code AgentsWhat Claude Code subagents are, why they help, and how to add your first one.
- Writing Your First Custom AgentA step-by-step guide to authoring a focused, effective custom subagent.
- Multi-Agent OrchestrationFour patterns for coordinating multiple agents — fan-out, pipeline, orchestrator-worker, and verify/critic — and when each earns its overhead.
- Agent ArchitectUse this agent to design a new Claude Code subagent or review an existing one — scoping, description, toolset, model, and output contract. Examples — "design an agent that triages flaky tests", "review my code-reviewer agent for scope creep", "why won't Claude auto-delegate to my agent?".
- Context WindowThe context window is the maximum text — measured in tokens — an LLM can consider at once: prompt, conversation, documents, and its own output combined.