TL;DR and verdict
Anthropic's article on folding subagents into the main loop tells you to use fewer of them, and the videos built on it say "delete your subagents". The article still keeps three cases and gives you a test for everything else s1. This pack is the three files that pass that test (a research scout, a read-only reviewer, an isolated builder), the fourth file we ran through the test (a test writer), and the script that ran it.
- The scout, the reviewer and the builder each answer one keep-case and each has its reason written in its
description. - The fourth agent, a test writer, went through the fold test: six tasks, two runs each, once as a subagent and once folded into a skill. Folded into a skill it passed 12/12. As a subagent it passed 11/12, at 0.410 dollars per run on average against 0.262, and 72 seconds against 36.
- So the test writer lost its file. The folded version never scored worse.
Verdict: keep the three files, and put every other agent through the fold test before it gets a file. Skip the scout for quick lookups, never send the builder into code your main session is editing, and read the reviewer's "unverified" list as carefully as its verdict. The limits are real: twelve runs per side on one repo, and the one subagent miss was a test command our project settings did not allow. Run it on your own repo.
Sourced synthesis
The article keeps subagents for three cases. Use them when a single agent loop hits measurable performance degradation from context bloat, when multiple tasks run in parallel with fresh context windows that can be discarded, or when a single agent struggles to select the right tool or faces conflicting instructions in the system prompt s1.
The fold-back test. Build a small end-to-end eval, fold in one subagent, and keep it as a subagent only if the folded version scores worse, then repeat s1. The article is written for Claude Platform agents and does not talk about Claude Code files, so we apply its test by analogy s1.
How to split if you keep one. Divide by context: give each subagent a piece of work that needs little from the rest of the system and have it hand back a compact result s1. That is why the scout carries a return contract and the reviewer an answer shape.
A subagent file is a Markdown file with YAML frontmatter. Only name and description are required, and tools inherits every tool available to subagents if omitted s2. So a read-only agent must list its tools explicitly. To keep a reviewer from spawning helpers, omit Agent from its tools list or add it to disallowedTools s2.
You write the files by hand. Claude Code 2.1.198 removed the /agents wizard: ask Claude to create or manage subagents, or edit .claude/agents/ directly. It also made subagents run in the background by default s24 s3.
maxTurns and isolation: worktree do what the builder needs. When the subagent reaches the maxTurns limit, Claude Code returns its output marked as partial s2. Worktree isolation gives the subagent an isolated copy of the repository branched by default from your default branch rather than the parent session's HEAD, and the worktree is cleaned up if the subagent makes no changes s2. Version 2.1.295 fixed subagents in their own linked worktree being shown the parent session's git branch s3. We ran on 2.1.294.
Reads fan out, writes stay single. Fan out for reads, stay single for writes s8. That is why the pack has one builder and never a crew.
Fan-out costs tokens, and on ordinary searches it finds nothing more. Multi-agent setups typically use 3-10x more tokens than single-agent approaches for equivalent tasks s4. In a 288-run benchmark, recall was 97-100% in every condition, and the cost per run rose by 74% to 116% on Haiku 5.5 and by 143% to 221% on Opus 5.5 s5. The scout pays when the read is big and your session has more work to do afterwards.
A reviewer needs evidence, or it invents findings. In one issue, a reviewer flagged correct code because it lacked version information, and the main agent relayed the finding unverified s12. Our reviewer file therefore refuses any finding without a quoted line. A reviewer that ends up approving everything has also stopped working s11, so check now and then that yours still finds something.
Agent folders rot. One developer reported that 16 imported agents never spawned in two weeks s10. A background subagent can also stall on a permission prompt, as the open issue on worktree-isolated subagents shows s13.
Anthropic's own research system is a fan-out. It shows where parallel reads pay s14. Most coding tasks have fewer truly parallelizable parts than research does.
Code
Install note: put the agent files in .claude/agents/ of your project. They are picked up within a few seconds of being saved, unless the agents directory did not exist when the session started, in which case restart s2. The reviewer's conventions line (money in integer cents, domain functions never mutate, errors thrown as ValidationError, NotFoundError or ConflictError) describes our sample invoicing API: replace it with your own conventions.
The scout answers the context-bloat case. It has Read, Grep and Glob only, runs on the cheap haiku model, and returns at most 12 lines: the answer, the proof as path:line, and what it did not find. Drop it in as .claude/agents/scout.md and ask for one scout per independent question, in parallel.
scout.md
---
name: scout
description: Read-only researcher for one question about this codebase that needs many files read but only a short answer back. Use proactively, one scout per independent question, in parallel.
tools: Read, Grep, Glob
model: haiku
---
You answer one question about this codebase. Read what you need. Never edit anything.
Return at most 12 lines:
1. The answer, in plain words, first.
2. The proof: the files and lines that show it, as path:line.
3. What you did not find or are not sure of.
No code block longer than 5 lines.
The reviewer answers the fresh-eyes verification case. Read, Grep and Glob only, no Agent, so it cannot edit or spawn. Hand it the spec and the diff (git diff main...<branch>), and verify every finding yourself before acting on it. Drop it in as .claude/agents/reviewer.md.
reviewer.md
---
name: reviewer
description: Read-only code reviewer. Use after a change is built, with the spec and the diff in the prompt. Returns a verdict with file:line evidence. Never edits.
tools: Read, Grep, Glob
model: sonnet
---
You review one change against its spec. The spec and the diff are in your prompt; read the surrounding code you need to judge them.
Look for what breaks: wrong behaviour against the spec, an edge case the code or its tests miss, a broken convention of this repo (money in integer cents, domain functions never mutate, errors thrown as ValidationError, NotFoundError or ConflictError).
Answer in this shape, nothing else:
VERDICT: PASS or FAIL
FINDINGS (most serious first, at most 5):
- [high|medium|low] path:line - what breaks, and the line that proves it, quoted
UNVERIFIED:
- anything you suspect but could not prove from the code
No style remarks. No finding without a quoted line.
The builder answers the separate-component case. isolation: worktree gives it its own copy of the repo and branch, and maxTurns: 40 stops a builder going in circles. Give it one self-contained piece while you keep working, then merge after the reviewer passes it. Drop it in as .claude/agents/builder.md and change the install and test commands to yours.
builder.md
---
name: builder
description: Builds one self-contained component with a clean interface, tests included, in its own git worktree. Use when a separate piece can be built while the main session keeps working. Never for changes to code the main session is editing.
isolation: worktree
maxTurns: 40
model: inherit
---
You build exactly the component in your prompt, in this worktree, and nothing else.
1. Run `git branch --show-current` and `git rev-parse --show-toplevel` and report both.
2. If node_modules is missing, run `pnpm install --frozen-lockfile`.
3. Write the code and its tests. Follow the conventions in README.md.
4. Run `pnpm test` and `pnpm typecheck` until both are green.
5. Commit on your branch with a one-line message.
Report in at most 10 lines: branch, files changed, test count before and after, anything you did not do.
The test writer is the fourth file, the one the fold test removed. It is here so you can run the same test on it, or use it as the template for the agent you are about to add. If you keep it, it goes in .claude/agents/test-writer.md.
test-writer.md
---
name: test-writer
description: Writes vitest tests for one module of this repo. Use proactively when the user asks to add or improve tests for a file or module.
tools: Read, Grep, Glob, Edit, Write, Bash
model: inherit
---
You write tests for exactly one module.
1. Read the module and the code that calls it. Read the existing test file for it, if any.
2. Add the missing cases to the test file under test/ (create it if none exists): boundaries, empty and invalid input, every branch, and anything the code promises in a comment.
3. Never edit files under src/. If a test reveals a bug, keep the test, mark it `it.fails`, and say so.
4. Run `pnpm test` until the suite is green.
Report in at most 6 lines: the test file, the cases added, the test count before and after.
The project settings used for the runs. The builder and the test writer only run what the settings allow, so an allow list that misses a command can cost you a run: that is how our one subagent miss happened. Merge the lines you need into .claude/settings.json.
ledgerly-settings.json
{
"permissions": {
"allow": [
"Bash(pnpm test)", "Bash(pnpm test:*)", "Bash(pnpm typecheck)", "Bash(pnpm install:*)",
"Bash(npx vitest:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)",
"Bash(git add:*)", "Bash(git commit:*)", "Bash(git branch:*)", "Bash(git rev-parse:*)", "Bash(git worktree list)",
"Edit", "Write"
]
}
}
ledgerly-settings.json on GitHub
The fold-test harness, in four files. run-one.sh runs one task as the subagent or folded into a skill, with the same user prompt. score.py applies the pass rule decided up front: suite green, no source file changed, and the planted bug caught. mutations.py holds one planted bug per module. jobs.txt lists the six tasks, two runs each, alternating variants. The paths point at our scratch folder and our sample modules, so change the root path and the mutations to match your repo before you run them.
run-one.sh
#!/bin/bash
# One fold-test run: run-one.sh <variant agent|skill> <task> <n>
# Copies ledgerly, sets up the variant, sends the same user prompt, scores the result.
set -u
V=$1; T=$2; N=$3
ROOT=/private/tmp/subagents-bench
W=$ROOT/eval/runs/$V-$T-$N
rm -rf "$W"; mkdir -p "$W"; cp -R "$ROOT/ledgerly/." "$W/"
cd "$W"
if [ "$V" = skill ]; then
# Fold: the subagent's prompt becomes a skill in the main loop; the agent file moves aside
mkdir -p .claude/skills/test-writer
BODY=$(awk 'f>=2{print} /^---$/{f++}' .claude/agents/test-writer.md)
{ printf -- '---\nname: test-writer\ndescription: Write vitest tests for one module of this repo. Use when the user asks to add or improve tests for a file or module.\n---\n'; printf '%s\n' "$BODY"; } > .claude/skills/test-writer/SKILL.md
git mv .claude/agents/test-writer.md .claude/test-writer.agent.md.aside
git add -A .claude && git commit -qm "eval: fold test-writer into a skill"
fi
FILE=$(python3 -c "import sys;sys.path.insert(0,'$ROOT/eval');from mutations import MUTATIONS;print(MUTATIONS['$T'][0])")
START=$(date +%s)
claude -p "Add tests for $FILE." --model opus --setting-sources project,local \
--output-format stream-json --verbose --permission-mode acceptEdits > run.jsonl 2> run.err
END=$(date +%s)
# Score
SRC_CHANGED=$(git status --porcelain -- src | wc -l | tr -d ' ')
npx vitest run > after.txt 2>&1 && GREEN=1 || GREEN=0
TESTS=$(grep -Eo 'Tests +[0-9]+ passed' after.txt | grep -Eo '[0-9]+' | head -1)
python3 - "$W" "$T" <<'PY'
import sys; sys.path.insert(0, "/private/tmp/subagents-bench/eval")
from mutations import MUTATIONS
w, t = sys.argv[1], sys.argv[2]; f, old, new = MUTATIONS[t]
p = f"{w}/{f}"; s = open(p).read(); open(p, "w").write(s.replace(old, new))
PY
npx vitest run > mutant.txt 2>&1 && KILLED=0 || KILLED=1
git checkout -q -- "$FILE"
python3 "$ROOT/eval/score.py" "$W" "$V" "$T" "$N" "$SRC_CHANGED" "$GREEN" "${TESTS:-0}" "$KILLED" "$((END-START))" >> "$ROOT/eval/results.jsonl"
tail -1 "$ROOT/eval/results.jsonl"
score.py
# Parse one run's stream-json and write a result row
import json, sys
w, v, t, n, src_changed, green, tests, killed, wall = sys.argv[1:]
delegated = skill = False
result = {}
for line in open(f"{w}/run.jsonl"):
try: e = json.loads(line)
except Exception: continue
if e.get("type") == "assistant":
for b in e["message"].get("content", []):
if b.get("type") == "tool_use":
i = b.get("input", {})
if b["name"] in ("Agent", "Task") and i.get("subagent_type") == "test-writer": delegated = True
if b["name"] == "Skill" and "test-writer" in json.dumps(i): skill = True
if e.get("type") == "result": result = e
passed = int(src_changed) == 0 and green == "1" and killed == "1"
print(json.dumps({
"variant": v, "task": t, "run": int(n),
"invoked": delegated if v == "agent" else skill,
"pass": passed, "green": green == "1", "srcChanged": int(src_changed), "killed": killed == "1",
"tests": int(tests), "wallSec": int(wall),
"costUsd": result.get("total_cost_usd"), "durationMs": result.get("duration_ms"), "turns": result.get("num_turns"),
"usage": result.get("usage"), "modelUsage": result.get("modelUsage"), "isError": result.get("is_error"),
}))
mutations.py
# One planted mutation per golden task: (task id, file, old, new)
MUTATIONS = {
"money": ("src/domain/money.ts", "if (value < min) {", "if (value <= min) {"),
"customer": ("src/domain/customer.ts", "name.trim() === \"\"", "name === \"\""),
"invoice": ("src/domain/invoice.ts", 'invoice.dueDate < now.toISOString()', 'invoice.dueDate <= now.toISOString()'),
"validation": ("src/domain/validation.ts", "quantity < 1", "quantity < 0"),
"migrations": ("src/store/migrations.ts", "{ customer: 0, invoice: 0, invoiceNumber: 0 }", "{ customer: 0, invoice: 0, invoiceNumber: 1 }"),
"router": ("src/http/router.ts", "decodeURIComponent(m[i + 1])", "m[i + 1]"),
}
jobs.txt
skill money 1
agent customer 1
skill customer 1
agent invoice 1
skill invoice 1
agent validation 1
skill validation 1
agent migrations 1
skill migrations 1
agent router 1
skill router 1
agent money 2
skill money 2
agent customer 2
skill customer 2
agent invoice 2
skill invoice 2
agent validation 2
skill validation 2
agent migrations 2
skill migrations 2
agent router 2
skill router 2
baseline-kill.sh checks the mutations first: each one must make the existing suite fail, or survive when it should, before you trust the eval.
baseline-kill.sh
#!/bin/bash
# For each mutation: apply on a scratch copy of ledgerly, run the suite, report killed/survived
set -u
SRC=/private/tmp/subagents-bench/ledgerly
for t in money customer invoice validation migrations router; do
W=$(mktemp -d /private/tmp/subagents-bench/eval/mut-XXXX); cp -R "$SRC/." "$W/"
python3 - "$W" "$t" <<'PY'
import sys; sys.path.insert(0, "/private/tmp/subagents-bench/eval")
from mutations import MUTATIONS
w, t = sys.argv[1], sys.argv[2]
f, old, new = MUTATIONS[t]
p = f"{w}/{f}"; s = open(p).read()
assert s.count(old) == 1, (t, s.count(old)); open(p, "w").write(s.replace(old, new))
PY
(cd "$W" && npx vitest run >/dev/null 2>&1) && echo "$t survived" || echo "$t killed"
rm -rf "$W"
done
Do this Monday
- Run
claude --version, and note that/agentshas been a pointer since 2.1.198: you create agent files by editing.claude/agents/or by asking Claude s24. - List the agent files you have today, and write each one's keep-reason in one sentence. If you cannot, it is a candidate to fold into a skill.
- Copy
scout.mdandreviewer.mdinto.claude/agents/, and adapt the reviewer's conventions line to your repo. - Copy
builder.md, check your allow list covers its test and typecheck commands, and give it one self-contained piece of work on a branch. - Make a golden set of 6 prompts for the agent you doubt, each with a pass rule you fix before running: green suite, no source file changed, a planted bug caught.
- Run
baseline-kill.sh(adapted) to prove every planted bug fails the current suite. - Run each task twice as the subagent, move the agent file aside, put the same instructions in a skill, run each task twice again, and read which tasks flipped, not only the score.
- Keep the agent file only if the skill scores worse. Otherwise delete it.
Measurements
The runs were on Claude Code 2.1.294 with Opus 5.5 on 2026-11-08. They are small: twelve runs per side on one repo for the fold test, two runs per side for the scout.
Fold test: test writer, 6 tasks x 2 runs x 2 variants
| Variant | Invoked | Pass | Avg cost $ | Avg wall s |
|---|---|---|---|---|
| agent | 12/12 | 11/12 | 0.410 | 72 |
| skill | 12/12 | 12/12 | 0.262 | 36 |
The only failure: agent/router/2 left a red test in test/router.test.ts ("matches the root path": expected null not to be null). Every run killed its module's planted mutation, and no run edited src/.
Scout, measured on the main session (mainCtx is the main session's context size, spawns the number of scouts started, durS the duration in seconds)
| Run | mainCtx | spawns | cost $ | durS | turns |
|---|---|---|---|---|---|
| audit-inline-1 | 45868 | 0 | 0.457 | 55 | 15 |
| audit-inline-2 | 47476 | 0 | 0.433 | 47 | 12 |
| audit-scout-1 | 30505 | 3 | 0.267 | 17 | 1 |
| audit-scout-2 | 33937 | 3 | 0.344 | 25 | 3 |
| inline-1 | 32294 | 0 | 0.273 | 29 | 7 |
| inline-2 | 33345 | 0 | 0.272 | 36 | 10 |
| scout-1 | 28966 | 3 | 0.223 | 18 | 1 |
| scout-2 | 30390 | 3 | 0.257 | 20 | 2 |
The "audit" rows are the big read (how every built-in middleware of a large open source framework rejects a request). The other rows are three small questions. On the small questions the scout saved almost nothing. The scouts ran on haiku.
Go further
Agent Teams are a different mechanism. Teams are sessions that message each other, behind an experimental flag, and nothing in this pack needs them s3.
Fan-out costs more than a chat. Anthropic's own research system measures its multi-agent cost against a chat, not against a single agent, so do not read that figure as subagents versus one loop s14. Our comparison against a single agent is the scout table above.
Subagent versus skill, in one line. A subagent starts with a fresh, isolated context; a skill runs in your main conversation, where the session already knows the repo. That is why the folded test writer was faster.
Forks and resuming. A fork inherits the whole conversation instead of starting fresh, and a stopped subagent can be resumed with its full history. We did not test either; read the subagents docs before you rely on them s2.
Several builders. Parallel builders writing at once were out of scope. The rule to start from is "reads fan out, writes stay single" s8.
Persona agents. Architect, product manager and other org-chart agents are what the test removes. Anthropic's article warns the agent architecture becomes a copy of the org chart s1.
FAQ
Does the scout always save context? No. On our three small questions it saved almost nothing, and fan-out on ordinary searches found nothing more at a higher cost s5. It paid on the big read, where the main session stayed smaller.
Why does the reviewer not have Edit or Write?
So it cannot fix what it finds, and omitting Agent stops it from spawning helpers s2. Leaving tools out would give it every tool, because omitted tools inherits them all s2.
My builder's worktree did not contain my uncommitted work. Is that a bug? No. The worktree is branched by default from your default branch, not from where you are s2. Commit or merge what the builder needs first.
The test writer lost on your repo. Will it lose on mine? Maybe not. We ran twelve runs per side on one small repo, and the subagent's one miss was a test command our settings did not allow. Run the harness on yours and read any run that flips, as the article recommends s1.
Can I make the reviewer wait instead of running in the background? Subagents run in the background by default since 2.1.198 s24. The docs describe asking Claude to wait for its report and a setting that makes it wait; check the subagents docs for your version s2.
AIDive