Three subagent files that still pay
A Claude Code subagent file is a Markdown file that defines a helper with its own fresh context. Anthropic says to use fewer subagents, and it keeps them for a few cases, with a test. We wrote the files it still keeps, ran each one on a real repo, and ran its fold test on one more agent. Setup: Claude Code 2.1.294 with Opus 5.5, runs made on 2026-11-08, on a small TypeScript invoicing API and on the Hono repo.
The catch is that popular advice says to delete your subagents, while Anthropic's article keeps them for specific cases and gives a test. We ran that test on the agent every collection ships, a test writer. Folded into a skill, it passed all twelve runs. Three files survive: a read-only scout, a read-only reviewer that passed a green change and still flagged a risk nobody asked about, and an isolated builder that shipped a whole feature in its own copy of the repo while the main session kept working.
What a subagent file is, and Anthropic's test
A subagent is a helper with its own fresh context. In a big repo, everything your session reads stays in its context, which is its working memory, and that fills up. A subagent works like a colleague who gets a ticket, reads half the codebase and sends back a short note.
You create an agents folder inside your .claude folder, and each subagent is a Markdown file in it. At the top you write a name and a description that says when to use it. Those are the only required fields. The description matters more than it looks, because it is what Claude reads when it decides whether to call the helper at all. When we typed the agents command, Claude Code told us the wizard had been removed, so you write the file yourself or ask Claude to. The sub-agents documentation covers the format.
Anthropic's applied AI team wrote an article on folding subagents back into your main agent, aimed at their platform. It keeps subagents for three cases: your context bloats, you need parallel work in fresh contexts you throw away, or your agent cannot pick the right tools. Everything else can usually be a skill, which is the same instructions loaded into your main session when needed. The test: build a small eval, fold the subagent in, and keep the subagent only if the folded version scores worse.
The cost of a subagent is that it starts blind. It only knows what you put in its prompt, and every handoff can drop a detail. So before you write any file, name the case it answers.
Anthropic's fold test on a fourth agent
The fold test is Anthropic's way of deciding whether a subagent earns its file, and it runs on an eval, a fixed set of tasks you run the same way every time with a pass rule you choose beforehand. We applied it to the test writer, the agent almost everyone adds because every collection ships one. It is a subagent that writes tests for a module, never touches your source, and runs the suite until it is green.
The method: keep the agent file as it is, copy the same instructions into a skill, and run every task more than once with the agent. Then move the agent file aside and run the same tasks again with the skill. Nothing is lost if the test goes against the file, because you only move the instructions.
We ran this on our small invoicing API with one prompt per module, such as "add tests for the router", six tasks with two runs each per variant. The pass rule was fixed up front: the suite must be green, no source file may change, and the new tests must catch a planted bug. A planted bug is a tiny change in the code that the old tests missed, so a good new test must fail on it.
| Variant | Invoked | Pass | Avg cost | Avg wall time |
|---|---|---|---|---|
| Subagent | 12/12 | 11/12 | $0.410 | 72 s |
| Folded into a skill | 12/12 | 12/12 | $0.262 | 36 s |
The subagent missed once. On the router, it tried a test command our project settings did not allow, so nobody ran its new tests and one of them was red. The folded version took about half the time, because the main session already knew the repo and did not have to brief a helper from scratch. The folded test writer answers sooner and costs less on every request, and you lose nothing. Anthropic's sibling article says setups with many agents typically burn a lot more tokens than a single agent, and our runs point the same way.
The test writer fails the fold test, because folded it does at least as well for less. The limit is that this is a small eval of twelve runs per side on one repo, and the miss was partly our permissions. Run it on your own repo and read any run that flips. We wrote the skill, ran both versions, and the agent file went, because the folded one never scored worse.
File one: the read-only scout
A scout is a subagent that can only read and search, and it hands back a few lines with the proof. Without it, a question that needs many files read makes your main session read them all and carry every line afterwards.
You give it the read and search tools and nothing else, so it cannot edit a file and cannot start helpers of its own. You put it on Haiku, Anthropic's small, cheap model, because reading and searching do not need your best one. You also write a return contract, the shape of the answer you require: the answer first, then the file and line that prove it, then what it did not find. In the description, you tell Claude to use it for questions that need many files read, one scout per question, in parallel.
We cloned Hono, a large open source web framework, and asked for an audit of how all twenty-seven of its built-in middleware reject a request. We ran the audit inline with no agents, then with scouts in parallel, each taking a share of the folders. Both ways returned the same answer, down to the same middleware and the same status codes. Two runs each:
| Measure | Inline, run 1 / run 2 | Scouts, run 1 / run 2 |
|---|---|---|
| Main context at the end (tokens) | 45,868 / 47,476 | 30,505 / 33,937 |
| Cost | $0.457 / $0.433 | $0.267 / $0.344 |
With the scouts, the main session ended about a third lighter, because it read their short notes instead of every file. That room matters when you keep working in the same session: your next task starts with less clutter and less to forget. The scouts ran on the cheap model, so the whole run cost less. That is the keep case Anthropic describes: the big read happens somewhere you throw away, and your session keeps the room for the work that comes after.
Now the limit. On small questions that only need a few files, the scouts saved almost nothing. A benchmark on dev.to found the same on ordinary searches: fanning out found nothing more and cost a lot more. The main session also passed on the scouts' answer without opening the files itself, so check the proof lines before you act on them. Send a scout when the read is big and your session has more work after it, and skip it for a quick lookup.
File two: the read-only reviewer
A reviewer is a subagent with fresh eyes that can only read. When your tests are green, it is tempting to merge a change nobody has read, and the session that wrote the change is the worst one to judge it, because it already believes its own plan. The reviewer sees the spec and the diff, which is the list of lines the change adds and removes.
You give it the read and search tools only. You leave out edit and write, so it cannot fix what it finds, and you leave out the agent tool, so it cannot start helpers. Anthropic's docs say exactly that: keep a reviewer read-only by leaving the agent tool out. Then you write the answer shape into the file: a verdict, pass or fail, then each finding with its file, its line and the quoted code, then what it could not prove. One more rule keeps it honest: no style remarks and no finding without a quoted line, so every finding comes with a line you can open and check yourself.
We handed it a real change, a spreadsheet export of open invoices written by our builder, with the spec and the full diff. It came back in nineteen seconds with a pass and one low finding about a customer record that might be missing. Under what it could not prove, it flagged two things nobody asked about. A customer name starting with an equals sign could run as a formula in a spreadsheet, and the rows were sorted as text, which works only while invoice numbers keep the same length. That is a reviewer passing a green change and still flagging a risk, and it did so without touching a single file.
We checked each point ourselves. Nothing deletes a customer, so the missing-record finding cannot happen, but the formula risk and the sort are worth fixing. The limit is that a reviewer only knows what it can read, so it marks the rest as unproven, and you verify every finding before you act on it. Run the reviewer after the build and before the merge, and read its unproven list as carefully as its verdict.
File three: the isolated builder
A builder is a subagent that writes code in its own worktree, which is a second copy of your repo, on its own branch, in its own folder. It suits a piece of work that stands on its own and should not block your session while it is built.
You set the isolation field to worktree, and Claude Code creates that copy for it and cleans it up if nothing changed. You also set a turn cap, so a builder going in circles stops and hands back what it has, marked as partial. Without a cap, a stuck builder can keep spending turns on the same failing test while you wait for nothing. In the instructions, you tell it to report its branch, run the tests and the type check until both pass, and commit.
We asked ours for a spreadsheet export of open invoices, with customer names that can contain commas and quotes, tests included. It went to the background, and while it worked we asked the main session a different question: which invoices can be voided, and where that rule lives. The main session answered with the exact line in the code, and the builder never got in its way. The builder came back in about a minute and a half with a commit on its own branch and fourteen new tests, all passing. Our main branch did not change until we chose to merge. We merged only after the reviewer passed it, and main simply moved up to the builder's commit, with no merge commit at all. You always see the builder's work as a branch you can read, test and merge, or throw away.
One article on fanning out puts the rule in a single line: fan out for reads, stay single for writes. The limit is that the worktree starts from your default branch, not from where you are, so work you have not committed is not in it. Never send it to code your main session is editing, and never run a crew of builders writing at once. Give the builder one piece that stands alone, keep working, and merge after the review.
Verdict: three files and one test
Anthropic says to use fewer subagents, and it is right, but three files still earn their place, each for a reason you can name. The scout keeps a big read out of your main session. The reviewer gives you fresh eyes that can only read. The builder writes a separate piece in its own copy of the repo. Write that reason into each file's description, because that is what Claude reads when it decides whether to call it. If you cannot write the reason in a single sentence, that is usually the sign the agent should be a skill instead.
The test writer did just as well as a skill, so its file went, and yours probably can too. Skip a subagent for a quick question, for code your session is already editing, and for any persona with no context reason to exist. In those cases a helper costs you a briefing, a wait and a handoff, and gives you nothing your session could not do. Agent teams, which are sessions that message each other, are a different thing, and nothing here needs them.
The one rule is the one Anthropic wrote: before any new agent gets a file, fold it into a skill, run both, and keep the file only if the skill scores worse.
AIDive