Subagents

A subagent runs a task in its own context window and hands back a summary. Use one to keep noisy work out of your main conversation, or to route a task to a cheaper model.

What it is

A subagent is a separate Claude instance the main session can spawn to handle one scoped task. It runs in its own context window and returns only a final summary. The back-and-forth it took to get there never enters your main conversation. That is useful for two different reasons: keeping your context clean, and routing a task to a cheaper model on purpose.

The smallest working example

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after writing code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code reviewer. For each issue, explain the problem, show the current code, and provide an improved version.

• tools is explicit and short. This subagent can only read and search, not edit or run commands.
• model picks a specific tier for this subagent only, independent of whatever model your main session is using.
• The body below the frontmatter is this subagent's entire system prompt.

How it behaves

• Subagent files live in .claude/agents/ (project) or ~/.claude/agents/ (personal), scanned recursively.
• Omitting tools inherits every tool the main thread has, including MCP tools. Worth setting explicitly for anything you did not build yourself.
• model accepts sonnet, opus, haiku, a full model ID, or inherit (the default).
• Three built-in types ship with Claude Code: Explore (read-only, fast model by default), Plan (read-only, used in plan mode), and general-purpose.

When not to use one

A subagent is for context isolation and, optionally, cost control. If the task needs to repeat across many items in a fixed structure, that is a workflow. If it should trigger automatically when Claude recognises a pattern, that is a skill. If you need to trigger it yourself by name on demand, that is a slash command.