Delegation

The mechanics of subagents, and the three uses that pay for themselves the first day.

You know the pitch. This is the part after it.

The file

A subagent is one markdown file in .claude/agents/. The frontmatter is the configuration; the body is the system prompt.

---
name: reviewer
description: Reviews a diff against a plan and reports gaps. Use after any multi-file change.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---
You review. You do not fix. Report only gaps that affect correctness or the stated requirements, with file and line. Style preferences are not findings.

Four lines do the work. description is how Claude decides to use it on its own, so write it as a “use when” sentence. tools is a hard list; leave out Edit and Write and the agent cannot change a file no matter what it is told. model: haiku for errands, sonnet for judgement, opus only when the task is the hard part. memory: project gives it its own notes across sessions, kept separate from yours.

Since June subagents run in the background by default. You keep typing, they report when done. They can spawn their own subagents, and a fork (/fork style, inherits your whole conversation) is the exception to “starts clean.”

Three uses

The scout. Read-only, Haiku, finds where things live before you touch them. This is the one on the Work page. Its whole value is that 40 file reads happen in its context, not yours.

The reviewer. Sees only the diff and the plan, not the reasoning that produced the change, so it is not grading its own work. Anthropic ships this as /code-review; the file above is the custom version when you want it checked against a specific plan. Tell it to report gaps, not preferences, or it will invent findings to justify its existence.

The specialist you keep re-explaining things to. If you paste the same five paragraphs of context into a fresh session every week, that is a subagent with memory: project and those paragraphs as its body.

When not to

A subagent does not see your conversation. If the task needs the last twenty minutes of context, a fork, or doing it yourself, is right. And every subagent starts a cold cache, so a chain of tiny subagent calls costs more than one session doing the work.

Cost, in numbers you can check

/usage shows what each errand cost and, from 2.1.251, the prompt cache hit ratio for the main conversation. Run the scout exercise once with model: opus and once with model: haiku and compare. That comparison is the whole argument.

Read more