Subagents

Here is a session that goes wrong without anything failing. You ask why the nightly digest email arrives twice. Claude searches the project, reads the scheduler, reads three job handlers, reads the queue configuration, greps the migrations and prints two log files. Then it tells you, correctly, that a cron entry and a boot-time registration both schedule the same job.

The answer is one sentence. Getting it filled a large part of your context window with files you will never look at again, and they stay there, competing with the work you actually wanted to do.

Subagents exist for exactly this shape of problem.

What a subagent is

A subagent is a second Claude, spawned by the first, working in its own context window. It has its own system prompt, its own set of tools and its own permission handling. It does the job it was handed and returns a report. What it read along the way does not come back with it.

The isolation runs in both directions, and the second direction is the one that catches people out. A subagent does not see your conversation history, the files Claude has already read, or the skills you invoked twenty minutes ago. It starts from the delegation message Claude writes for it, plus its own instructions.

Some things do reach it. A custom subagent loads the same CLAUDE.md hierarchy your main conversation loads, so your project conventions travel with it. The two built-in research subagents — Explore, for searching a codebase, and Plan, used while you are in plan mode — deliberately skip CLAUDE.md to keep research fast and cheap. That is worth remembering: if a constraint matters for an investigation and it only exists in CLAUDE.md, say it in the prompt.

What it looks like

Defining your own

You get built-in subagents for free. You define your own when you keep spawning the same kind of worker with the same instructions.

A subagent is a markdown file with YAML frontmatter, in one of two directories you have seen before. .claude/agents/ belongs to the project and is committed for your team. ~/.claude/agents/ is personal and follows you into every project.

---
name: test-triage
description: Runs the test suite and reports only the failing tests with their error messages. Use when tests are failing and you want the causes rather than the output.
tools: Read, Grep, Glob, Bash
model: haiku
---
 
You diagnose failing tests. Run the suite, then for each failure report the
test name, the assertion that failed and the most likely cause in one line.
 
Do not report passing tests. Do not attempt fixes.

Only name and description are required, and the description does the same job it does in a skill: it is what Claude matches your request against when deciding whether to delegate. Write it in the words you would actually say.

The body becomes the subagent's system prompt. Note what the one above spends its words on — the shape of the output. That is usually the most valuable thing you can specify, because a report you have to re-read in full has given back part of what the isolation bought you.

model is optional and inherits the session's model when you leave it out. Naming a smaller, cheaper model for mechanical work is one of the quieter wins here: the subagent that greps for a symbol does not need the model you chose for architecture.

As with skills, the fastest way to get one is to describe the worker you want and let Claude write the file.

Restricting what it can reach

tools is an allowlist: name the tools and the subagent has only those. disallowedTools is the reverse, removing specific tools and leaving the rest.

This is worth more than it looks. A reviewer subagent whose tool list contains no editing tool cannot edit, no matter what it decides. Compare that with writing "review only, do not change anything" in its prompt, which is a request of the same kind as a CLAUDE.md rule. It is the advisory-versus-enforced distinction from the hooks lesson, appearing in a second place.

A subagent inherits the session's permission context and can tighten it. It cannot quietly grant itself more than the parent session allows.

The same logic runs in the other direction, and it is a genuinely useful trick. A subagent can declare an MCP server of its own, connected while it runs and disconnected when it finishes. A browser server you need for one testing agent does not have to be in your main configuration, where its tool listing would cost you something in every session of every project. Give the capability to the worker that needs it and nowhere else.

Asking for one

Three ways, escalating in how much of the choice you are making yourself.

Name it in a sentence — "use the test-triage agent on the auth suite" — and Claude usually delegates. @-mention it and that specific subagent runs; Claude still writes the task prompt, but the choice of worker is yours. Or start the whole session as one with the --agent flag, so the main thread itself takes on that subagent's prompt, tools and model.

Delegation the rest of the time is Claude's judgement, matched against your request and those descriptions. Like skill invocation, it will sometimes be wrong in both directions.

When delegation costs more than it saves

This is the part that gets skipped, and it is why people come away thinking subagents are overrated.

The fresh start is a real cost. Twenty turns of shared understanding between you and Claude is exactly what a subagent does not have. Delegating a task that depends on all of it means paying to re-explain, and accepting a worse briefing than the one you built up by hand.

Latency. A subagent starts cold and has to find its footing. For a small, targeted change you already know how to describe, the round trip is slower than doing it.

The results still land in your window. Isolation applies to the work, not the answer. Six subagents each returning a thorough report have re-imported the problem you were avoiding. Ask for the conclusion.

Some questions do not need one at all. If what you want is reusable instructions rather than isolation, that is a skill, and it runs in the conversation you are already in. And for a question about something already in your context, /btw is cheaper than delegating: it sees your conversation, has no tools, and its answer is not added to your history.

The rule of thumb that survives contact with real work: delegate what is self-contained and verbose. Keep what is iterative and shared.

What to take away

A subagent is a second Claude with its own context window, its own system prompt and its own tools, which does a job you hand it and returns only its report. The reason to use one is isolation — an investigation that reads twenty files leaves those twenty files behind and gives you the conclusion, which is the only part you were going to use. Define one as a markdown file in .claude/agents/ for your team or ~/.claude/agents/ for yourself, where the description decides when Claude delegates and the body becomes the system prompt; spend most of that body specifying the shape of the report. Restricting tools is enforcement rather than instruction, which makes a read-only reviewer genuinely read-only. And delegation is not free: a subagent starts with none of your conversation, takes time to get going, and its results come back into your window, so it pays off on self-contained verbose work and loses on the iterative kind.

Next: plugins, which take the skills, hooks, subagents and servers you have accumulated and turn them into one thing another person can install.