A subagent is a focused helper with its own prompt, tools, and context window. Build one so Claude can delegate work — like code review — without cluttering the main thread.
Why: a subagent runs in its own context window with its own instructions, so heavy work (reviewing, searching, researching) does not bloat your main conversation. When: use one for a self-contained job you want done with a specific lens. Where: the main session calls it and gets back just the result.
Main session ──delegates──► Subagent (own context + prompt + tools)
▲ │
└────────── returns result ◄───────┘
The subagent's long investigation stays in ITS window, not yours.Why: a subagent is a markdown file — frontmatter defines who it is and what it can touch, the body is its system prompt. When: run /agents to scaffold one interactively, or write the file directly. Where: project agents live in .claude/agents/; the description tells Claude when to invoke it.
<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: Reviews code changes for bugs, security, and style. Use proactively
right after writing or editing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. Given a diff, report issues grouped by
severity (critical / warning / nit) with exact file:line references.
Be concise. Do not rewrite the code — just review it.Why: a subagent should hold only the tools it needs — a reviewer reads, it does not push to git. When: list tools to restrict it, or omit the field to inherit everything. Where: give cheap, parallel jobs a smaller model to save time and cost.
tools: omit -> inherits all of the main session's tools
list -> only those tools (least privilege — safer)
model: omit -> uses the session's model
haiku -> fast & cheap for simple, high-volume helpers
opus -> for deep reasoning subagents
Run /agents to create, edit, and inspect your subagents.