Claude Code Subagents: What They Are and How to Use Them

Separate Claude instances Claude Code spawns to handle a focused task in their own context window, with their own model and a restricted toolset. They do verbose work — tests, logs, docs — and return only a short summary, keeping the main session fast and cheap.

Define one as a small Markdown file in .claude/agents/ (project) or ~/.claude/agents/ (personal), with a name, a tight description, the tools it may use, and a model. Claude Code invokes it on a description match or when you name it explicitly; setting a cheap model such as Haiku on simple subagents is the key step, and /agents manages them.

Indirectly. They keep verbose output out of your main conversation — which you otherwise re-send on every turn — and can run on a cheaper model. They still consume tokens of their own, so the saving is the model choice and cleaner context, not the subagent being free.

Haiku for simple, high-volume jobs (tests, log triage), Sonnet for exploration and refactors, Opus only for genuinely hard reasoning. Always set it explicitly — an unset model inherits your session’s. The model field accepts haiku, sonnet, opus, fable, a full model ID, or inherit.

A subagent is a separate instance with its own context — best for volume or isolation. A skill is a reusable instruction set that loads on demand — best for repeatable know-how. An MCP server is an external tool or data source Claude calls — best for reaching live systems. They compose rather than compete.

Roughly seven times a standard session when teammates run in plan mode, because each maintains its own context window. Keep teams small, keep tasks self-contained, and shut teammates down when they finish.

Not from native billing alone across API keys and cloud providers. Routing Claude Code through an AI gateway resolves each request to a developer and meters spend per key, so subagent and agent-team usage shows up attributed rather than lumped into one number.

In .claude/agents/ for project-scoped subagents (version-controlled, shared with the team) and ~/.claude/agents/ for personal ones that follow you across projects. Organisation-managed settings override both — how a platform team standardises subagents across a fleet — and on name collisions the more specific scope wins.