Commission a Subagent to Research and Write Your Skill

You already know two moves from this blog, and both assume you already have the answer. When you know exactly which files a task touches, you stop letting the agent guess and point it there directly - that’s deterministic context. When you carry a procedure in your head, you write it down once as a skill, a checked-in file an agent loads on demand, and you can even build a meta-skill that interviews you and writes the next one, the way A Skill That Writes Your Skills does. That move transcribes a procedure you already carry. This piece is for the procedure nobody has yet.

Both moves need you to know something in advance. Deterministic context needs you to know where the files live. Skill authoring needs you to know the procedure worth freezing.

Now the case neither covers. A vendor ships a breaking major version, and nobody at your company has ever reconciled its changes against your code. The migration guide is generic; your repo has three years of wrappers layered over the same handful of call sites. You are about to become the first person who has done this reconciliation, and you are about to do it fifteen times, once per service in the fleet, because that’s how many services still import the old client.

This is not the retrospective move either. Let the Failure Distribution Write Your AGENTS.md mines your own past transcripts to decide what a rules file should say: internal history, after the fact. This is external and prospective. A vendor’s docs, reconciled against your repo, before anything has broken.

The waste has a name, and it is the villain of this piece: re-derivation, every service paying full price to rebuild a reconciliation the service before it just built, because nobody wrote down where the vendor’s truth and the repo’s truth disagree.

Here is the whole arithmetic, stated up front so you can check it as the piece runs. Fifteen honest migrations, each done from scratch, cost 102,000 tokens. One commissioned reconciliation, frozen into a skill and reused fifteen times, costs 45,500 for the same fleet. The 56,500-token gap is what this piece derives, and every step of it checks with a pencil.

The gap isn’t “we don’t have a skill for this yet.” It’s “nobody has done the research that skill would be made of.”

Before any arithmetic, one question about your own repo. Think of a migration or integration you have actually run with an agent, something a vendor changed on you rather than something you designed. Could you have written the corrected call sites from memory, before the agent touched a single file? Or did somebody, you or the agent, have to read the vendor’s guide and grep the repo first, because nobody had worked out where the two disagreed?

If you could write it from memory, you already have the procedure. Freeze it into a skill the direct way and close the tab; you don’t need a subagent to discover something you already know.

If you had to go find out, keep reading. Everything from here is what that finding-out costs, run out to the point where you never pay it twice.

A skill worth commissioning is one where the honest answer to “do you know this yet” is no.

Fix one concrete case and carry it through everything below. A platform team runs a fleet of 15 microservices. Each was scaffolded by a different squad over three years, and each wraps the same vendor HTTP client, call it httpclient, in its own thin retry-and-timeout shim, because that’s what the starter template did in 2023 and nobody has touched it since.

The vendor ships v4. Three things change: retries becomes maxAttempts, timeoutMs becomes timeout, and the onFail callback is gone entirely; v4 expects you to check .error on the result after the call instead. The first two are renames. The third is a removal, and a rename-only codemod, a script that rewrites code by swapping exact old names for new ones, cannot make it, because it only knows pairs and has no idea a whole shape changed.

Call the third change what it is: the landmine, the one edit a mechanical rename tool cannot even see. v4’s client quietly ignores an onFail key it doesn’t recognize, so the callback never fires again, nothing errors, and the code compiles clean.

The wrappers aren’t identical. Some layered their own backoff on top, and one buries the retry options three calls deep. But every one of them passes the same three v3 keys through to the underlying client, because that’s what the starter template exposed to copy from.

billing-service is the one traced by hand below. It has four call sites into the old client.

The fleet is one migration wearing fifteen coats, and every coat answers to the same three changed options.

Count what the honest work costs before any tool speeds it up. One service, one reconciliation, and tally what the agent reads:

The external half is fixed. The guide does not change per service, so 2,600 is the same number every time. The local half is open-ended, because nobody has told the agent which of your call sites carry the three options the vendor changed, so it searches broadly and reasons from nothing. That’s the 4,200. One honest, correct reconciliation: 6,800 tokens, per service.

Now scale it the way the fleet actually runs. Fifteen services means the guide half happens fifteen times: 15 x 2,600 is 39,000 tokens spent reading one migration guide.

36,400 of those tokens are pure duplication. The same document, reread fourteen times by somebody who had already read it.

The local half never gets cheaper either. Nothing learned on billing-service makes the search on payments-service narrower, because in the honest-from-scratch version nothing gets written down.

The guide holds 2,600 tokens of information, and the fleet rereads it into 39,000.

Before any codemod or skill runs, do the obvious thing first: read each of billing-service’s four call sites, compare it to v4’s documented signature, and mark it rename, structural, or clean. This hand-trace is the ground truth everything later gets checked against.

Three of the four sites need an edit. Two are pure renames, and a rename-only codemod fixes both without anyone reading a line of vendor documentation. The third is the removal. v4’s client does not reject the old onFail key, it silently ignores it, so the callback never fires again, the code compiles clean, and the tests on the retry path still pass, because they mock the callback directly instead of exercising a real retry. The failure shows up the first time a real retry happens in production.

So, from your own trace: 4 sites, 3 edits, exactly 1 invisible to a rename-only tool. One of billing-service’s four call sites hides a change no codemod can make. Remember that fraction: 1 in 4. It gets paid off exactly, two sections down, on the whole fleet.

Ground truth before tools: 3 of 4 sites change, and 1 of those 3 is invisible to any rename-only codemod.

Two ways to run this migration, and both fail somebody.

Run the codemod alone and ship it. You fix two of the three needed changes in every service for free, and you ship the landmine in every service too, because nothing errors and nothing tells you the callback stopped firing.

Run the full reconciliation by hand, correctly, on every service. Reread the guide, regrep the repo, reason it out again. You catch the landmine every time, at 6,800 tokens and real attention per service, and it is exactly the step someone skips on the fourteenth service of a Friday afternoon, because being right has stopped depending on the arithmetic and started depending on somebody’s discipline under deadline pressure.

Cheap and silently wrong, or right and expensive enough that somebody eventually stops paying. There is a third option, and by now you have probably thought of it: do the reconciliation once, under inspection, on the reference service, and freeze the result into a file. Call it the frozen reconciliation. The deliverable is a skill that performs the migration, carrying the landmine catch as a named step:

1. Bump httpclient to ^4 and run the install.
2. Run the codemod: npx httpclient-codemod v3-to-v4 src/
   Catches the pure renames - 2 of billing-service's 3 needed edits.
3. Fix what the codemod missed. See reference.md for the full mapping.
4. Check every call site that passed onFail. v4 drops the callback
   silently - replace it with a check on result.error. This is the
   landmine the codemod can't see.
5. Verify: typecheck, then the full suite. Don't stop until both pass.

Step 4 is the whole point. It is the one line in either workflow that names the landmine out loud, where the codemod path never names it and the by-hand path names it only if somebody remembers to look.

The frozen reconciliation turns “catch the landmine” from a habit somebody might skip into a step a file always names.

This piece is named for the move, so here is the actual dispatch. You commission a subagent, a separate agent with its own context window, with a brief like this:

You are researching the httpclient v3-to-v4 migration for this repo,
and writing a skill from what you find. Do NOT edit any code.

Inputs: the vendor's v4 migration guide, and this repo's wrappers
around the v3 client. Use billing-service as the reference.

1. Read the guide. List every option whose name or shape changed.
2. Find every call site into the old client in the reference service.
   Compare each to v4's documented signature. Mark it rename,
   structural, or unchanged.
3. For every change, record the old form, the new form, whether a
   rename-only codemod catches it, and how to catch it if not.
4. Write .claude/skills/httpclient-v4/ (SKILL.md, reference.md,
   examples.md) so a later agent can run this migration on any
   service in the fleet without rereading the guide.

If you did not verify a mapping against both the guide and the repo,
do not write it.

Notice what the brief never asks for: opinions. It asks for verified pairs, the guide’s claim next to the repo’s reality, because those pairs are the only thing a later service needs. And it ends with the honesty clause a good map gets: an unverified mapping must not be written down, because it is about to be trusted fourteen more times.

The commission costs the external half of one honest pass (2,600), the local half on the reference service (4,200), and about 1,200 to write the three files. 8,000 tokens, once.

After that, every service gets cheap, because the skill already names the three exact options that changed and the file that carries them. The open-ended search becomes a targeted grep plus a read of the already-distilled mapping: 1,900 of local work plus 600 to load the skill itself. 2,500 tokens per service.

The commission buys the research once and hands every later service a finished answer where it used to face an open question.

Hold onto this table. The rest of this piece is rows of it.

Row 1 is negative on purpose. The commission is a real upfront cost: 8,000 for a skill used exactly once, where one honest reconciliation alone would have cost 6,800. Break-even lands at 1.86 services, so the skill wins by the second service, and by service 15 it is ahead by 56,500, the number from the top of this piece, reconciled exactly against row 15.

Now pay off the fraction you planted. The fleet premise says every service was scaffolded from the same starter template and carries the same four-site shape, so billing-service’s ratio recurs fifteen times over: 60 call sites across the fleet, 45 of them needing an edit, and 15 of those edits invisible to a rename-only codemod. All fifteen silent, all shipping clean through a codemod-only migration. The premise is an assumption and stays one; the hand-trace proves 1 in 4 for billing-service, and the fleet total is an extrapolation, checkable per service and worth checking. If it holds, step 4 of the skill is the only line in either workflow that names those 15 sites out loud.

This is the same amortization shape as Cache the Explore: pay once, reuse N times, row 1 negative on purpose. The axis differs. That piece caches where things are, in a file with a days-long shelf life, thrown away and rebuilt per slice of one repo. This one caches how to do a task, in a file meant to outlive the run that made it and get forked forward across vendor majors, reused across a fleet now rather than across sessions on one repo later.

Every row’s skill column carries the landmine catch for free. The ad hoc column carries it only if nobody got tired of doing it right.

Two things the ledger does not price, and both decide whether its numbers are real.

Where the skill lands. A skill can live in two places: your personal skills directory, which follows you across every project, or the repo’s .claude/skills/, which ships with the code. Left alone, an agent often writes to the personal one, because it works instantly for whoever ran the commission. That is exactly why it fails a fleet: the skill works for you and stays invisible to whoever owns payments-service next sprint. The 8,000 pays off across fifteen services only if the other fourteen teams can see the file. Commit it to the repo’s .claude/skills/ and pin the rule in your rules file:

## Skills
Author all new skills under .claude/skills/ in this repo, never the
user-level skills directory. Skills are team artifacts.

How many services per run. Nothing stops someone from pointing the skill at all fifteen services in one pass and walking away. Resist that. A batch that hits an error at service eleven leaves the agent’s window stuffed with ten services’ worth of diffs at the exact moment it most needs room to think about the eleventh. The skill’s own step 5, typecheck then the full suite, is built to run as a checkpoint between services; treat it that way.

The ledger’s numbers hold only if the whole fleet can reach the file, and only if the verify step gates each service as it lands.

Four things worth naming plainly.

Anthropic’s own skill-creator skill interviews you about a procedure you are assumed to already have, and shapes your answers into a well-structured skill. That is a different job than this one. For a migration nobody has run, the honest answer to that interview is “I don’t know yet,” so here the subagent interviews the vendor’s docs and your repo instead of interviewing you. Once the research exists, skill-creator’s structural conventions, the SKILL.md and reference.md split and progressive disclosure, are still the right shape for the output. It shapes a result you already have. It cannot produce one nobody has yet.

The dispatch pattern is prior art, too. Sending a subagent off to write a docs/research/<topic>.md is already common practice beyond skills, and parallel research agents writing findings to a file is documented elsewhere. What this piece adds is the constraint on the deliverable: a skill, versioned, checked into .claude/skills/, built to be reused and forked, where a one-off research doc serves one migration and gets read once.

An MCP server pointed at the vendor’s current docs is the live alternative, the move Bootstrap a Service You Don’t Understand makes when you are learning a service interactively, in one session. It gives you current docs every session, at the cost of re-reading them every session. The commissioned skill trades that currency for zero re-read cost, until the vendor ships the next breaking change and the skill goes stale; the risk is the same either way, just paid at a different time. If the vendor breaks compatibility every few weeks, that trade stops favoring the skill. The frozen reconciliation assumes a landscape stable enough to be worth freezing.

And the caution that outranks the savings: a skill is only as good as the reconciliation that produced it. The token ledger has no column for whether the research was actually right. A sloppy commission freezes sloppiness into the next 14 services exactly as cheaply as a careful one freezes correctness, and 2,500 tokens per service is a bargain only when each run is pointed at a correct mapping. Review the SKILL.md the way you would review a teammate’s pull request before the fleet starts trusting it. That review is a human step, every time.

The ledger prices the reconciliation. Whether the reconciliation was right is a column only a human review fills in.

Row 15, one more time: 102,000 tokens done honestly from scratch, 45,500 commissioned once and reused, a difference of 56,500. The skill column caught the landmine in every one of those rows without asking anyone to remember to be careful on a Friday afternoon.

The skill is a file now, checked into the repo, and it carries an expiry the way Cache the Explore’s map does, except its shelf life is measured in vendor major versions rather than weeks. That is the durability argument, and it is why the skill gets forked instead of rewritten: when v5 ships, you fork the v4 skill and point a subagent at the new guide to diff the delta against work you have already pinned down.

Nothing in this piece checks whether the v4 skill is still true once v5 ships. That is the open question it hands forward: what forces a stale, checked-in skill to get re-verified before an agent trusts it again, the same way a hook can fail a run against a stale map.

And once the skill exists, it is an artifact your whole team can install, and the habit no longer lives in one person’s head. That is the second half of this problem, and Package the Workflow, Not the Prompt is where it goes. Commission the skill first. Package it second.

Do the reconciliation once, under inspection. Then ship that file fifteen times.

About the numbers. Every token figure in this piece (the guide-read cost, the per-call-site reasoning cost, the commission, the per-service skill cost) is a toy number invented for traceability, not a measurement of any real vendor, repo, or bill - the same convention as Cache the Explore. They were chosen so every later figure checks with a pencil, and a script re-derives all of them from the same raw inputs before publishing. The fleet-wide landmine count, 1 per service and 15 total, is an extrapolation from a stated assumption: that every service was scaffolded from the same starter template and shares the same wrapper shape. The hand-trace proves the 1-in-4 ratio for billing-service alone. Swap in your own numbers and the shape holds: the commission is negative on row 1, ahead by row 2, and the landmine gets caught in every later row whatever the counts are.

For the per-tool mechanics, see Subagents for running the research in its own window, Skills for the file format and progressive disclosure, and MCP servers for the live-docs alternative.