Your Subagents Aren't Using Your Skills

We run a Claude Code environment with several hundred installed skills: house review gates, deployment checklists, domain playbooks, debugging protocols. They exist so that an agent doing a task doesn't reinvent — or skip — the procedure the last hundred sessions already refined.

Then we counted something. Across roughly fifteen subagent dispatches in a single working session — implementers, reviewers, verifiers — the number of agent reports that mentioned invoking a skill was zero. Not "fewer than we'd like." Zero. Every one of those subagents had the full skill roster available to it. None of them reached for it.

Availability is not awareness

When an orchestrating agent spawns a subagent, the subagent genuinely does inherit a lot: the same skill roster listed in its context, the project's instruction files, the same hooks firing on its tool calls. What it does not inherit is state — the parent's transcript, anything the parent loaded mid-session, or any of the corrections the parent accumulated along the way. Every dispatch is a cold start.

In other words: your subagent can see the library from its desk. Nobody told it to go read anything, and it's being graded on finishing the assignment, not on trips to the library.

The deeper reason is a recall problem that shows up everywhere in agentic systems — the same one that pushed us to give our skill library a graph instead of a list: selection needs a cue. A skill fires when the task text strongly matches its trigger description — and a tight execution brief ("apply this diff, run these tests, report back") deliberately doesn't emit those cues. The better you scope your briefs, the less likely unprompted skill discovery becomes. Discipline in one dimension suppresses initiative in another.

We'd actually solved this problem once before — for humans. Our delegation workflow for handing tasks to teammates has always included a "Skills to Invoke" section in the task package, because nobody expects a colleague to psychically discover the right internal playbook. We just never gave our software agents the same courtesy.

The three levers (and the one that fails silently)

There is no skills parameter on a subagent dispatch. The orchestrator has exactly three ways to transfer skill knowledge:

1. Pick an agent type that is the skill. A dedicated code-reviewer or verifier agent carries its procedure in its own system prompt. Solid, but it only covers work important enough to deserve a dedicated agent definition.
2. Name the skill in the brief. A verbatim directive — Invoke <plugin>:<skill> first. — turns discovery into instruction-following, which subagents are good at.
3. Inline the skill's operative content. Paste the checklist, the command sequence, the standard itself into the brief.

Here's the failure mode that made us formalize this instead of leaving it to habit: lever 2 fails silently on agents that can't invoke skills at all. Read-only reviewer and verifier agents — often the most frequently dispatched agents in a disciplined setup — typically have file-reading and shell tools but no skill-invocation tool. Write "invoke the review checklist first" into their brief and you've issued a dead instruction. The agent can't comply, won't say so, and the orchestrator walks away with false confidence.

In other words: before you tell an agent to use a skill, check whether it's physically able to. If it isn't, you have to hand it the contents, not the pointer.

So the dispatch rule we shipped branches on the agent's tool roster: skill-capable agents get named skills, skill-less agents get inlined operative content. And the receive side got a contract too — every subagent report must now carry a Skills: line, where Skills: none is an acceptable answer and omitting the line is not.

That last clause matters more than it looks. Our zero-of-fifteen baseline was only possible retroactively, because we went digging. Silence is indistinguishable from non-use unless you make the null case mandatory.

Prove the surface exists before you build on it

The policy fix costs a few paragraphs of instruction text. The measurement layer required knowing two things about the platform that we refused to assume: does a pre-tool-use hook actually fire when a subagent is dispatched, and can a hook inject context the model actually receives?

We ran a spike with a discipline we now apply to every probe like this: three outcomes, not two — pass, fail, and probe-broken. A control that silently fails to arm is indistinguishable from a genuine pass; both print success.

• A throwaway hook appended every payload it received to a file, and returned a context injection containing a marker token with an instruction: include the exact string ROGER-XYZZY-7291 in your final response.
• Before trusting anything, a probe-check re-pointed the same hook at an event we already knew how to trigger, confirming the harness loads and executes hooks at all. No verdict counts until that prints PROBE OK.
• The measurement run dispatched a trivial subagent headlessly and captured structured output.
• A no-hook control ran the identical dispatch with no hook configured — if the marker showed up there, the probe was invalid, not passing.

The verdicts: the hook fires, under the tool name Agent — never the legacy Task — which matters, because an unanchored Task|Agent matcher would also catch unrelated tools. And the marker appeared in the model's result field, absent from stderr, absent from the control: context injection genuinely reaches the model.

In other words: don't resolve platform behavior from documentation or memory when a twenty-minute experiment can resolve it from reality — and design the experiment so that "my experiment is broken" has its own distinct signature.

Measure first. Advise later, if ever.

With the surface proven, the obvious move is a hook that routes: watch outgoing briefs, detect when one maps to a skill it doesn't name, and inject a suggestion. We deliberately didn't build that. Two reasons.

First, a pre-dispatch hook fires after the brief is written. The dispatch is already committed; the subagent launches with the un-annotated brief. At best, an advisory improves the next dispatch. A hook here is a measurement instrument, not a router — the thing that actually shapes briefs is the dispatch rule the orchestrator reads before writing them.

Second, briefs are a different text distribution than the prompts our skill-routing index was calibrated on. A user prompt is a sentence; a dispatch brief is two thousand words. Long text over-matches topic signals, and a suggestion engine that's wrong on every dispatch is worse than none. Before any advice is worth showing, you need data on whether the suggestions would have been right.

So the hook we shipped is log-first. On every subagent dispatch it records one line: which agent type was dispatched, a hash and length of the brief (never the text — measurement shouldn't create a surveillance log of your own orchestration), which skills the brief explicitly named via the directive convention, and which skill the routing index would have suggested for that content. The advisory path exists, but it ships dark behind an environment flag until the log says the suggestions are signal.

One more measurement subtlety, caught in final review before the data could mislead anyone: the headline "candidate-miss rate" — briefs where the index suggested a skill the brief didn't name — conflates the two compliant behaviors. A brief to a skill-less verifier that correctly inlines a skill's content still matches that skill's topic signals, and logs as a miss. Aggregate miss-rate would overstate non-compliance for exactly the agents the policy treats differently. The report now segments every metric per agent type, so the calibration decision reads the right numbers.

In other words: an instrument that measures compliance has to encode the policy's own exceptions, or it will quietly manufacture evidence that the policy is failing.

Did any of this work?

The build itself became the first test case. The dispatch rule and executor contract shipped as the first tasks of the plan; every subagent dispatched afterward — six implementer and reviewer waves across two repositories — complied with the day-old contract, Skills: line and all. The extraction refactor held a frozen regression suite at 10/10 before and after; the hook's nine-case suite and the report's segmentation tests went green; eight independent review seats — including an adversarial pre-execution review that caught three genuine blockers in the plan — signed off before the final merge verdict.

And the first live measurement row exists: minutes after enabling the hook, a real dispatch logged source: "agent-dispatch", agent type, brief hash, named skills, suggested skills. The instrument that would have caught our zero-of-fifteen months ago is now always on.

Where this goes: declaration, not discipline

The dispatch rule works, but it lives in an orchestrator's instruction context — which means it competes with everything else there and gets re-applied by judgment on every dispatch. It doesn't compound. The forward contract we've recorded for our workflow-graph direction moves the declaration into structure: each graph node that dispatches an agent declares skills: [...] in its node schema, validated against the skill map at graph-build time — an unresolvable skill reference is a build error, not a runtime hope. The brief compiler, not the executor, resolves the declaration: named directives for skill-capable rosters, inlined content for skill-less ones.

In other words: today a person remembers to tell each agent what to read. The end state is that the workflow itself knows — and a workflow that references a skill that doesn't exist refuses to build.

The checklist

If you run subagents against a skill library of any size:

1. Count it. Grep your agent reports for skill invocations. Expect the number to be lower than you think; ours was zero.
2. Make the null case speak. Require a Skills: line in every agent report — "none" allowed, silence not.

1. Aim for declaration. Anything a human re-types into every brief belongs in structure that validates at build time.

The gap isn't that agents are lazy. It's that we built libraries and assumed cold-started workers would browse them. They won't — but they follow instructions well, and they can be measured honestly. Start there.