| name | agent-orchestration |
| description | How to delegate work to subagents well — when to spawn one, how many, which model and effort level, how to write the delegation prompt, and when NOT to delegate. Load before starting any non-trivial task: research, codebase investigation, multi-file work, migrations, reviews, or anything that will read a lot of files. Also load when the user says "use agents", "delegate", "spawn subagents", "in parallel", "orchestrate", or asks why a delegation went badly, cost too much, or should be audited.
|
| allowed-tools | Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/delegation-audit.py*), Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/warm-start.py*) |
| when_to_use | Any task with more than one independent piece of work, any task that will read many files, any request to parallelize, and any time you are about to do a lot of exploration inline.
|
Agent orchestration
Your context window is the scarce resource, not tokens and not time. Every file
a subagent reads costs you nothing; every file you read costs you the rest of
the session. Delegation is context management first and parallelism second.
But delegation is not free. A subagent starts blind — it sees none of your
conversation — so it must re-derive context from scratch. Anthropic measured
multi-agent systems at ~15× the tokens of a chat interaction (single agents:
~4×). That spend is justified only when the task is big enough, parallel enough,
or context-heavy enough to earn it.
The decision, in order
Run these four gates before spawning anything.
Gate 1 — Is it self-contained?
A subagent cannot ask you or the user a question (AskUserQuestion is stripped
from every subagent). If the task needs a judgment call mid-flight, either
decide it now and put the decision in the prompt, or keep the work inline.
Gate 2 — Is the output smaller than the input?
Delegate when the work reads a lot and reports a little: test runs, log
trawls, grep sweeps, dependency audits, "where is X used". Do not delegate
when the work reads a little and writes a lot — you will pay cold-start cost
for nothing.
Gate 3 — Are the pieces independent?
Anthropic's own finding: multi-agent is ineffective for "domains requiring all
agents to share the same context or involve many dependencies between agents,"
and "most coding tasks lack sufficient parallelizable work." Two agents editing
the same call chain will conflict and duplicate. Split by file boundary or by
question, never by "half the feature."
Gate 4 — Would you rather have the finding than the files?
If yes, delegate. If you need the file contents in your own context to make the
next decision, read them yourself.
If any gate fails, do the work inline. Say so and move on — do not spawn an
agent to look busy.
How many, and how hard
Scale the fleet to the question, not to your enthusiasm. Anthropic's published
scaling rule:
| Task shape | Agents | Tool calls each |
|---|
| Simple fact-find ("where is X defined") | 1 | 3–10 |
| Direct comparison ("how do A and B differ") | 2–4 | 10–15 |
| Broad research / audit / migration survey | 10+, responsibilities explicitly divided | as needed |
A lead agent spawning 3–5 workers in parallel is the workhorse shape.
Parallel tool calling cut research time by up to 90% in Anthropic's testing.
Launch parallel agents in one message with multiple Agent calls. Sequential
spawns give you the cost of multi-agent with none of the speed.
Model and effort
Two separate dials, and confusing them is the most common routing mistake:
- Model = capability ceiling. What the agent is able to figure out.
- Effort = thoroughness. How many files it reads, tools it runs, steps it
takes before it stops. Not merely "thinking time."
Diagnose failure to pick the dial:
- Agent had all the context, clearly tried, and was still wrong → raise the
model. Knowledge gap.
- Agent skipped a file, didn't run the tests, stopped early, didn't check its
work → raise the effort. Thoroughness gap.
Routing defaults:
| Work | Model | Effort |
|---|
| Mechanical, precisely describable edits; questions about code already located | haiku / sonnet | low–medium |
| Ordinary implementation, feature work, research, most delegation | sonnet | inherit (default high) |
| Real architecture calls, subtle bugs, ambiguous or high-stakes judgment | opus | high–xhigh |
| Final adversarial verification of a risky change | opus | xhigh |
Effort levels are low, medium, high, xhigh, max. Default is high on
every supporting model (Opus 4.7 defaults to xhigh). Use max sparingly —
it is "prone to overthinking" and shows diminishing returns.
Omitting model means the agent inherits your session model. That is usually
right. Only override when you are confident a different tier fits — a cheap
worker for mechanical scanning, a strong one for the judgment call.
Local rules win. If CLAUDE.md or user instructions restrict which models
may be used, obey that over this table without comment.
Writing the delegation prompt
A subagent receives its own system prompt, your delegation message, CLAUDE.md,
and git status. It receives nothing else — not your conversation, not the
files you read, not the skills you loaded, not the decisions you made three
turns ago. (Explore and Plan skip even CLAUDE.md and git status.)
So every delegation prompt carries four things. Missing any one is the usual
cause of a bad agent result:
- Objective — the question to answer or the change to make, stated so it
can be answered without asking you anything.
- Output format — exactly what to return and how long. This is the only
lever you have on how much of your context the result eats.
- Tools and sources — where to look, what to use, what to ignore
(
vendor/, node_modules/, generated files).
- Boundaries — what is out of scope, and which other agents own the
neighbouring pieces. Explicit division of labour is what stops five agents
running the same grep.
Vague prompts cause duplicated and missed work. references/prompt-contract.md
has the template and worked examples.
What comes back
The agent's final message is injected into your context verbatim, and the user
never sees it. Two consequences:
- Bound the output in the prompt. "Return a file:line table, max 20 rows,
no prose" costs a fraction of "report your findings." Ten agents each
returning two pages of prose defeats the entire purpose of delegating.
- Relay what matters yourself. The user sees only your text. Summarize the
finding; never say "the agent reported" and stop there.
Do not fabricate or predict a pending background agent's result. If asked
before it lands, say it is still running.
Verification
The agent that did the work is the wrong one to grade it. For anything risky,
spawn a fresh reviewer that sees the diff and the criteria but not the
reasoning that produced them.
Prompt reviewers to flag only gaps that affect correctness or stated
requirements. A reviewer told to find problems will find some regardless, and
chasing all of them produces defensive over-engineering.
Anti-patterns
- Delegating the small thing. A one-file edit you can already describe is
cheaper inline than a cold-start agent.
- "Investigate X" with no boundaries. Unscoped exploration reads hundreds
of files and returns mush. Scope it or don't send it.
- Splitting coupled work. Two agents on one call chain conflict.
- Sending an agent to a file you haven't located. Locate first (one cheap
read-only agent), then hand exact paths to the worker.
- Expecting questions back. It cannot ask. Under-specified means it guesses.
- Unbounded returns. See above — the return is your context.
- Assuming it knows your rules. Restate the constraint that matters in the
prompt, especially for
Explore/Plan, which never see CLAUDE.md.
- Worktree isolation by default.
isolation: "worktree" costs setup time
and disk. Use it only when parallel agents write to the same files.
Delete the cold start before you fan out
A subagent's first ten to thirty tool calls are usually not the work — they are
orientation. What stack is this, where does the source live, how do I build it.
Every agent in a fleet re-derives that same map separately, and none of it
needs a model: where files live is a fact you can compute.
So compute it once:
python3 ${CLAUDE_SKILL_DIR}/scripts/warm-start.py
Then one line in every agent's system prompt:
First action: if .claude/briefing.md exists, read it. Never find or
ls -R to orient yourself.
Orientation collapses to a single Read. Measured on a real 97-file repo: a bare
find of source files costs ~745 tokens and returns only paths; the briefing
costs ~315 tokens and gives stack, package manager, build/test/lint
commands, layout, entry points, and known traps.
The output is deterministic and sorted, so an unchanged repo regenerates
byte-identically and stays prompt-cache friendly. Regenerate when the structure
moves. Full method, the cache-preload variant for large fleets, and what it
does not fix: references/cold-start.md.
Measure it instead of guessing
Every subagent's transcript, with per-message token usage, is on disk at
~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl. That makes
the only question worth asking about a delegation answerable exactly:
leverage = tokens the agent processed / tokens it returned to you
Run the audit — it needs no arguments, no network, and reads only local files:
python3 ${CLAUDE_SKILL_DIR}/scripts/delegation-audit.py
python3 ${CLAUDE_SKILL_DIR}/scripts/delegation-audit.py --all
Read the result this way:
| Leverage | Meaning |
|---|
| > 100x | The delegation did its job — heavy reading, small report |
| 10–100x | Fine, but the return could usually be tightened |
| < 10x | You paid cold-start cost to learn almost nothing — inline it next time |
The audit also flags any agent that returned more than ~800 tokens, because an
unbounded return is the one mistake that makes delegation worse than doing the
work yourself.
Use it when a session felt expensive, before adding another agent to a fleet,
and after changing a delegation prompt — the ratio tells you whether the change
helped. Advice about token economy is worth what you can verify; this is the
verification.
Cheapest delegation is a named one
Once you have spawned the same kind of worker twice, write it down as an agent
in .claude/agents/<name>.md. Its system prompt then loads into the
subagent's context, not yours: the output contract, tool limits, scope
rules, model, and effort all move off your budget, and the delegation message
drops from ~130 tokens to ~20.
Two more levers worth knowing before you fan out:
- Route big output through disk. If a return would exceed ~500 tokens, tell
the agent to write a file and return only the path plus a one-line verdict.
A 2,000-token report becomes ~40, and it survives
/clear.
- Preload skills with
skills: [name] rather than restating standards in
every prompt — subagents inherit none of yours by default.
Full ranking with measured numbers: references/token-economics.md.
Reference material
references/token-economics.md — what delegation actually costs, and the six
levers that cut main-context spend, ranked.references/prompt-contract.md — delegation prompt template, good and bad
examples, output-format recipes.references/patterns.md — the orchestration shapes: parallel scout, locate→
fix→verify pipeline, adversarial verify, writer/reviewer, fan-out migration,
loop-until-dry.references/mechanics.md — hard limits, tool filters, what loads into a
subagent, resuming agents, custom agent frontmatter spec.
