Why Aren't My Claude Code Subagents Using My Skills?

If a Claude Code subagent ignores an installed skill, check three things first: whether the skill is available to that agent, whether its tool permissions allow invocation, and whether the task tells it which procedure matters. Installation does not prove that a particular worker loaded or followed the instructions.

An early internal review found dispatch reports that did not mention skill invocation. That exposed a reporting gap; it did not prove every worker ignored all skill content. We added explicit handoff and evidence requirements, then began inspecting traces as well as summaries.

Availability is not awareness

Subagents have their own context and tool configuration. Current Claude Code documentation supports a skills field in a custom subagent definition to preload named skill content. Without preloading, discovery depends on available skills and tool access; a worker does not inherit the parent's conversation history automatically.

Start with the actual agent definition and active tools. A skill can be installed yet unavailable to a particular worker, or available but not selected for that task.

A tightly scoped brief may omit the cue that would otherwise lead to a skill. That is a useful hypothesis to test, not a universal rule about model behavior. Compare the requested procedure with the trace of what the worker loaded and did.

Human task packages benefit from a named procedure and a clear definition of completion. Agent handoffs need the same clarity, plus a check that the worker can access the procedure in the first place.

Four ways to provide the procedure

Current Claude Code offers a direct preload route as well as instructions in the brief. Choose the method that fits the worker's context and permission boundary.

1. Preload a known skill. In a custom subagent definition, put the relevant names under skills:. The host supplies their content at startup. Check that each skill resolves and is eligible for model invocation; missing or disabled entries are not evidence of successful loading.
2. Name the skill in the brief. For a worker with the Skill tool, request the specific installed skill and ask it to report whether invocation succeeded. Example: "Use the installed review skill for this diff, then report the checks performed and any unavailable steps."
3. Inline the needed checklist. If the worker cannot invoke a skill, give it the relevant operative instructions. Example: "Check authorization boundaries, changed callers and failure behavior. Cite the affected lines and tests. Do not edit files." Report this as supplied instructions, not a tool invocation.

Use a dedicated agent definition when the procedure belongs to that role. A reviewer can carry a focused checklist in its instructions and a restricted tool set. Read-only does not automatically mean skill-less; inspect the actual tools before deciding which path to use.

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.

A report line makes uncertainty explicit, but it is not sufficient evidence on its own. Separate preloaded content, a successful Skill call, an inlined checklist and no observed skill use. Compare those declarations with the available trace.

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 internal probe recorded dispatch under Agent and observed the injected marker in the result while the no-hook control omitted it. Treat that as evidence for the measured host version and hook configuration. Match the actual event/tool name rather than assuming old names or broad regular expressions remain correct.

A small controlled probe is useful when platform behavior matters. Record its version, inputs and control result, and keep probe failure separate from a product verdict.

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.

A hook can observe a dispatch and, depending on the host, supply context or block an action. Do not assume that an advisory rewrites an already supplied subagent prompt. If the worker must receive instructions, put them in its definition or brief and verify the resulting context.

Second, dispatch briefs differ from the user prompts a routing index may have been calibrated on. Length and multiple topics can distort matches. Measure suggestion quality on actual dispatch briefs before deciding whether to show advice.

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 implementation added an explicit Skills report line, regression tests and per-agent reporting. Those checks test the dispatch and measurement contract; they are not a controlled study showing better answers or fewer production errors.

The useful next step is to inspect repeated real dispatches: which procedure was requested, which form of content reached the worker and whether the output met its acceptance criteria. Keep missing traces as missing evidence.

Where this goes: declaration, not discipline

For reusable workflow graphs, declare required skills in the node contract and validate that they resolve before dispatch. The brief compiler can choose preloaded content, a named invocation or an inlined checklist based on the actual host and tool roster. This is a design pattern; each implementation still needs a test that the worker receives the intended instructions.

A structured declaration reduces repeated briefing work, but it does not replace output checks. A valid reference proves that a skill can be located, not that it was followed correctly.

The checklist

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

1. Count observed use. Inspect both reports and tool traces. Distinguish explicit invocations, preloaded or inlined instructions and cases where the evidence is missing.
2. Make the null case speak. Require a Skills: line in every agent report — "none" allowed, silence not.
3. Branch on the roster. Use preloading or named skill directives where supported, and supply the checklist when the worker cannot load it. Read-only status alone does not determine skill access.
4. Probe your platform with three outcomes. Pass, fail, and probe-broken — with a control run that proves the probe itself.
5. Log before you advise. A suggestion engine calibrated on the wrong text distribution is noise with confidence. Measure, segment by agent type, then decide.
6. Aim for declaration. Anything a human re-types into every brief belongs in structure that validates at build time.

Our implementation reference: https://github.com/Rhize-Media/rhize-plugins/tree/main/rhize-context-manager . The hooks reference documents the log-first agent-brief-router and its opt-in advisory flag.

Start with one failing dispatch and make the instruction path observable. Current host reference: https://code.claude.com/docs/en/sub-agents. Then compare the worker's actual checks with the task's acceptance criteria. The Rhize Plugins marketplace provides reusable review and coordination procedures, but the host configuration still determines what a worker can use.