(MOT-4223) llm-router: reference skill

[rohitg00]

What

A real skill for llm-router (skills/SKILL.md), replacing the auto-generated registry stub ("Worker on this mesh exposing 4 function(s)... no published skill exists for this worker yet") that agents currently get from directory::skills::get { id: "llm-router" }.

Covers, source-verified against current main:

• Calling models: chat (streamed via writer_ref), complete (including the content-must-be-blocks trap whose failure mode is a misleading stream ended without a terminal frame), abort, embed with its capability discovery.
• The catalog lifecycle: provider-fed via models::reconcile, the registered-but-not-reconciled split state (provider in provider::list, models missing) as the diagnostic signature, budget/supports semantics including the fail-open rule.
• Provider registration and the token binding: first-register mints, hash persisted in state scope llm-router key registry, raw token only in provider memory, the registration_rejected operator-action error, the recovery recipe (backup state, clear records, restart router, restart dead providers), and configured vs available with the dispatch-time flip-down.
• Configuration: default {api_key, api_url, max_tokens} slice injection with write-only api_key, the per-provider nullable system_prompt knob and its console set/unset rendering, hot-reload semantics.
• The identity prompt precedence (operator override, else provider-declared, else null with the harness fallback) and the never-errors guarantee.
• Trigger types: router::ready (provider re-declare rebind), models::changed, provider::changed.

Why

First slice of the worker reference wave: an audit of the released bundles found llm-router, session-manager, context-manager, approval-gate, and every provider shipping ~300-byte generated stubs. The router is first because its failure modes (no_provider_for_model, registration_rejected, provider_unavailable) are exactly the ones an operator meets during upgrades, and none of them were documented anywhere. The registration/recovery section is the runbook from a real 0.21 to 0.22 migration.

Pattern follows the harness mechanics reference (#589): one self-contained doc, no code changes.

Linear

Closes MOT-4223. Part of MOT-4222.

Reworked to the no-duplication norm

Same rework as #589: the function-catalog sections are gone, the API link (https://workers.iii.dev/workers/llm-router.md) covers surface questions, and the one per-function trap (router::complete takes content blocks, not strings) moved into the function metadata description where engine::functions::info serves it. The skill keeps only cross-function semantics: catalog split-state diagnostics, the token binding recovery runbook, prompt precedence, and ready-rebind behavior.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview, Comment	Jul 24, 2026 3:02pm
workers-tech-spec	Ready	Preview, Comment	Jul 24, 2026 3:02pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

llm-router contract documentation

Layer / File(s)	Summary
Routing and model catalog llm-router/skills/SKILL.md	Documents routing entry points, model selection, streaming, cancellation, embeddings, catalog APIs, and provider reconciliation.
Provider registration and configuration llm-router/skills/SKILL.md	Defines provider token binding, configuration, credentials, identity prompts, and hot-reload behavior.
Events, boundaries, and harness calls llm-router/skills/SKILL.md	Lists router triggers, persistence boundaries, streaming safeguards, and harness-invoked router calls.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Poem

A rabbit hops through routes so bright,
Models stream by day and night.
Tokens bind, prompts softly flow,
Catalogs tell what workers know.
Events thump: ready, changed—
The router’s contract is arranged!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the documentation-only llm-router skill reference added in this PR.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch llm-router-reference-skill

---

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.}

[github-actions]

skill-check — worker

0 verified, 48 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓
render	✓

Four for four. Nicely done.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@llm-router/skills/SKILL.md`:
- Around line 132-135: Clarify the prompt storage boundary in the
provider-declared prompt discussion: explicitly state whether declaration
prompts are persisted in the registry/configuration, retained only in memory, or
re-supplied after restart. Align the fallback, configuration-prefill, and
privacy/restart statements so they consistently describe the selected behavior.
- Around line 82-87: Update the recovery recipe documentation to describe
provider-scoped deletion or restoration of only the affected registry record,
rather than presenting `{}` as equivalent. Clearly label setting `llm-router`
registry to `{}` as an all-provider reset with broad impact, and retain the
required worker/provider restart and re-registration steps.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ffe77a92-fe00-49d7-99f5-f0e4ec82bf00

📥 Commits

Reviewing files that changed from the base of the PR and between e7c581f and 1decc65.

📒 Files selected for processing (1)

• llm-router/skills/SKILL.md

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Do not present {} as a provider-scoped recovery operation.

Setting the entire llm-router/registry value to {} invalidates every provider binding, not only the affected record, potentially causing a broad outage and simultaneous re-registration. Document a provider-scoped deletion/restore procedure and clearly label {} as an all-provider reset.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@llm-router/skills/SKILL.md` around lines 82 - 87, Update the recovery recipe
documentation to describe provider-scoped deletion or restoration of only the
affected registry record, rather than presenting `{}` as equivalent. Clearly
label setting `llm-router` registry to `{}` as an all-provider reset with broad
impact, and retain the required worker/provider restart and re-registration
steps.