(MOT-4164) iii-directory: pre-generate hook injecting a compact skills index

[rohitg00]

What

A harness::hook::pre-generate binding that appends a compact installed-skills index to the agent system prompt on every generation:

## Installed skill docs

Workers on this engine ship skill docs. Read one with
`directory::skills::get { id: "<worker>" }`; deeper docs are linked inside.
Full list: `directory::skills::list`.

- browser: Drive a real browser...
- harness: The durable agent turn loop...

• src/inject_index.rs, modeled line-for-line on fp/src/guidance.rs: engine parks the binding until the harness registers the trigger type, on_error: fail_open so a failure can never block a turn, empty-base guard so schema drift preserves the assembled prompt.
• Index built from scan_skills_merged (one row per worker overview, teaser from frontmatter description), 10 s cache, per-line and whole-section caps with an explicit truncation pointer. No engine calls in the hook path.
• New inject_index config knob, default false (opt-in). Read on every fire, so the configuration worker toggle takes effect without a restart or rebind.
• Six unit tests on the pure formatting and mutation paths; 255 lib tests pass, clippy clean.

Why

Agents currently learn what exists either from a hardcoded prompt (grows forever, drifts) or a discovery call (a turn and a round trip). With this hook the capability map arrives with the prompt, always current, and its cost scales with what is actually installed instead of with what the prompt author anticipated. fp proved the pattern for usage guidance; this generalizes it to discovery.

Pairs with #558 and #560: the minimal core stays static, per-worker guidance rides presence-gated hooks, deep playbooks are pulled on demand.

Status: live-validated on a rig

Ran the branch build as a second directory worker against a live engine (0.21.6, harness 1.4.2) and walked the full checklist:

• Disabled gate: direct hook invocation returns {"mutations": {}} while inject_index is false.
• Enabled: index builds from the real skill set on disk, 602 tokens for 30+ workers, capped format as designed.
• Composition in a real generation: a live session confirmed all three layers stacked in its system prompt (router operator override, fp guidance hook, this index) and quoted the section's first rows.
• Worker killed mid-run: the next generation completed normally (fail_open plus the binding dying with the worker connection).
• Config restored afterwards; the knob toggles without a restart as designed.

The live run caught one real bug the unit tests could not: the scanner aliases <worker>/SKILL.md to the on-disk id <worker>/index, so the original single-segment overview filter matched nothing and the index was always empty. Fixed with an explicit overview_worker matcher plus a regression test.

Two operational observations from the same run, for reviewers: with two instances of the worker connected, the configuration-update event load-balances to one of them, so the other keeps the old snapshot until reboot (inherent to duplicate instances, not this hook); and the hook function is invisible to engine::functions::list search because it registers with internal: true metadata, which is intended.

Draft: design review wanted, especially default-off vs default-on and the index format.

Linear

Closes MOT-4164. Part of MOT-4157.

Post-review simplification (applied)

A structured cleanup pass reworked the hook onto the canonical machinery: the injected text is now exactly directory::skills::index, built by a shared skills::build_index used by both the function handler and the hook, so overview classification (type: index clause included), teaser resolution, and the never-drop-a-worker budget policy cannot drift between the two surfaces. The cache rebuild moved outside the lock (concurrent generations are never serialized behind it) and the worker filter runs through the stale-tolerant registered-workers cache. Live re-validated: 19 installed workers injected, config gate and restore verified.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview, Comment	Jul 22, 2026 4:18pm
workers-tech-spec	Ready	Preview, Comment	Jul 22, 2026 4:18pm

[github-actions]

skill-check — worker

0 verified, 47 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓
render	✓

Four for four. Nicely done.

[coderabbitai]

Warning

Review limit reached

@rohitg00, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 53 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 889842dd-af1c-4794-970d-033cf26229af

📥 Commits

Reviewing files that changed from the base of the PR and between 28f44dc and 32a8dda.

📒 Files selected for processing (5)

• iii-directory/src/config.rs
• iii-directory/src/functions/skills.rs
• iii-directory/src/inject_index.rs
• iii-directory/src/lib.rs
• iii-directory/src/main.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch directory-skills-index-hook

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}