Tools the Agent Knows to Reach For

Picture a developer who installs a /test skill, a /refactor skill, and a /security-review skill, then opens an intent. The elaborator drafts twenty units. The hats run. The work ships. None of those skills get touched once. The agent had every tool sitting on the shelf and never knew the shelf existed.

That's the gap PR #298 closes. Until last week, hat subagents inside a H·AI·K·U unit were tool-blind to skills the user had installed. The harness exposed them, the agent could in theory invoke them, but nothing in the workflow ever told a subagent for this unit, reach for these. So nothing did.

The shelf nobody could see

Claude Code skills are slash commands — /test, /refactor, and whatever else a team has authored. They're first-class user customization. Teams ship them to encode house style: how tests should be written, how PRs should be reviewed, how a security pass actually runs in this org.

A H·AI·K·U run leans hard on subagents. Every hat in every unit is a fresh subagent with a tightly scoped prompt. The parent gives it a role, a scope, the inputs it's allowed to read, and the rule about how to relay results. Until this PR, it gave the subagent zero awareness of what skills were installed in the user's environment.

So the user's /test skill — the canonical way this team writes tests, with all the conventions baked in — sat unused while the builder hat wrote tests inline using whatever testing pattern the model defaulted to. A custom skill that never got the airtime its author expected.

Where the decision actually belongs

H·AI·K·U already has a phase for unification. The elaborator is the hat that takes a stage's inputs and decomposes them into units. It picks scope, dependencies, models, quality gates — every per-unit decision the rest of the workflow inherits. That's the place that sees the whole stage at once, and asking which skills would meaningfully accelerate this unit fits the work it's already doing.

The unit metadata is already where every other inheritance-shaped decision lives. One more field belongs there. That field is applicable_skills: — slugs only, no descriptions, no metadata, just a short list like [test, refactor].

Selection vs. inventory

The elaborator needs to see every installed skill to pick. The unit needs to remember only the picks. Those are two different lifetimes, and the design has to honor that.

The engine reads installed skills fresh on each elaboration, with more-specific definitions shadowing more-general ones. The elaborator sees the rendered list at the moment it's picking. The unit keeps only the slugs.

This is the same pattern H·AI·K·U uses for everything dynamic. The model registry lives in the harness. The hat definitions live on disk. The studio templates live in the plugin. Selections — this unit gets Opus, this unit closes FB-03, this unit reaches for /test — live in unit frontmatter where the work itself lives.

Inheritance without re-deciding

Once the unit ships with applicable_skills: [test, refactor], every hat dispatched on that unit inherits the list. The rendered block looks like this:

## Skills available
The unit author identified these skills as potentially useful for this unit. Invoke them via the standard skill mechanism when appropriate.

- `/test` — Write tests for code using TDD principles
- `/refactor` — Restructure code to improve quality without changing behavior

Every hat sees the same list, but each plays it differently.

None of them re-decide whether the skill applies to this unit. That call was committed at elaboration. They only decide whether to invoke it at this hat's slice of work. Descriptions re-resolve at dispatch time, so a skill the user uninstalled between elaboration and execution degrades to the slug alone — the slug is the record of intent, the description is convenience text.

A unit without skills declared skips the block entirely. No empty header, no scan cost. The elaborator is told to be selective: only annotate when there is clear relevance — don't bloat every unit. Most units don't get annotation, and the prompt for those units stays exactly the same as before.

The block is advisory, not permission

The skill block doesn't grant access. Every skill is already callable by the agent at the harness layer — H·AI·K·U doesn't gate skill invocation, the harness does. What changes is awareness, not access. Without the annotation, a hat that already knew /test existed could call it. With the annotation, a hat that didn't know /test existed now does. The awareness gap was the gap that was real, and it's the only one this PR closes.

That distinction matters because skills are uneven. Some are heavy slash commands that take over the conversation for several turns. Some are thin helpers that run in a single call. The hat has to judge fit per-task, and the judgment can't live in the block. The workflow shouldn't bake skill-execution semantics into itself anyway — skills are user surface, the user shapes them, the harness runs them, and the workflow stays out of that loop except to point at it.

The footprint

The surface is small.

The user's skill library used to be a separate world from the workflow — two systems with no channel between them. Now the channel runs through the phase that already does this kind of work, and the decision sits on the unit alongside model selection and the rest. Skills just hadn't been plumbed yet.

If you've got a /test, a /security-review, and a /refactor installed, the next intent you elaborate will see them. The units that benefit will say so. The hats that run on those units will know. Nothing about that should require the user to think about it — and after this PR, they don't.