Skip to main content
Without router mode, every installed skill competes for context budget in the model’s prompt window. As a skill library grows, native implicit discovery shortens descriptions to fit, makes skill selection less reliable, and fills context with inventory that rarely matches the user’s actual task. Router mode solves this by moving skill discovery out of the prompt and into a local SQLite catalog — so the prompt receives only the selected skill handle, not every installed description.

​
How the router works

Router mode builds a local SQLite catalog (skill-index.sqlite) from all installed skills under configured roots. When a user prompt arrives, the skill-router skill (automatically installed as the implicit first hop) runs a single skillspec route query against that index. The router uses a BM25-style lexical scoring algorithm over each skill’s name, description, tags, trigger phrases, and skill.spec.yml metadata, then applies an activation-anchor gate to prevent broad skills from winning on generic text overlap. The route decision is always one of three values: Router install also writes a visibility manifest and applies native harness controls so routed skills are manual-only (explicit-only) — the router is the only selection path while it is enabled. The manifest is the rollback boundary; restore always uses recorded file snapshots. Policy profiles let you layer operator-authored routing rules on top of lexical scoring. The three profile modes are:
  • route — normal router behavior with optional policy preferences
  • soft-passthrough — router remains the first hop but the active profile defaults to bypass; only allowlisted skills or matching rules can route
  • native-passthrough — router steps out of the hot path for high-throughput coding or focus modes; hooks and router skill are made explicit-only while allowlisted skills stay implicit

​
Install the router

Run skillspec router install once to create the router skill package in every configured skill root, write the visibility manifest, build the initial index, install prompt guard hooks, and write router config to ~/.skillspec/router/config.json.
You can pass multiple --roots entries when skills are shared across Codex, Agents, and Claude roots. After a successful install, restart your active harness sessions so they reload skill metadata and hook entries. skillspec router install creates:
  • A SkillSpec-backed skill-router skill with a SKILL.md and skill.spec.yml in each configured root
  • ~/.skillspec/router/skill-index.sqlite — the SQLite catalog
  • ~/.skillspec/router/visibility-manifest.json — the rollback manifest
  • ~/.skillspec/router/config.json — router lifecycle state
  • Managed Codex and Claude UserPromptSubmit guard hook entries
If you previously used ~/.skillspec/router as a bare SQLite file path, router install will detect the collision and ask for --force. The forced path moves the old file to ~/.skillspec/router/skill-index.sqlite before writing router config.

​
Build the index

The index is built automatically during router install and router enable. You can also build or rebuild it directly with skillspec index:
Directory paths resolve to skill-index.sqlite automatically. When router config exists and is enabled, prefer skillspec router index refresh instead — it reapplies explicit-only visibility controls and checks preparedness after rebuilding.

​
Route a query

Test routing decisions manually with skillspec route:
The JSON output includes decision, selected (skill path when use_skill), candidates with individual base_score and policy_score fields, bypass_reason, and an optional elicitation hint when the user has not yet chosen direct or durable execution mode.

​
Guard hook

The guard hook runs skillspec router guard before every model turn when the managed hook is installed. It verifies that the router index is fresh and applies repair if visibility or index drift is detected since the last turn.
In diagnostic mode (without --hook), the guard reports first_hop_ready, index status before and after any repair, and any visibility repair output:
When emitting harness hook JSON (--hook), the guard outputs a UserPromptSubmit-compatible block. On success it injects compact context telling the model that router mode is ready and that skill-router must be the first hop. On failure it emits a blocking decision with the concrete repair command. SkillSpec installs managed hook entries into the relevant hooks.json (Codex) or settings.json (Claude Code) for each configured root. It removes only the managed router guard hook entries when disabling or uninstalling — existing user hooks are never touched.Implemented root mapping:
  • <base>/.codex/skills → <base>/.codex/hooks.json
  • <base>/.claude/skills → <base>/.claude/settings.json
  • <base>/.agents/skills → <base>/.codex/hooks.json and <base>/.claude/settings.json (when .claude exists)

​
Policy profiles

Policy profiles let you tune routing behavior without editing router skill files.
1

Create a profile

--active marks this profile as the live profile in skill-index.sqlite. The route command reads the active profile from SQLite at query time — no restart needed.
2

Add rules to the profile

--anchor policy lets the exact skill:browser preference satisfy the activation-anchor gate, so the router can select the browser skill even when the query uses only the keyword browse rather than the skill name itself.
3

Inspect the policy

Always run policy get or policy show before editing an existing rule so you preserve existing predicates and preferences.
4

Explain a routing decision

The explanation includes base_score, policy_score, policy_reason, and which rules matched, so you can audit exactly why a candidate was selected.

​
Refresh the index after skill changes

When you add, remove, or change skills outside skillspec install skill, the router index drifts. Use skillspec router index refresh to repair visibility controls and rebuild the index:
For a read-only view of what has drifted before refreshing:
Status output includes new, changed, and missing skills, whether each is SkillSpec-backed or prose-only, and per-entry conversion advice pointing to skillspec import-skill for prose-only packages.

​
Enable and disable

Disable preserves router files, config, index, and manifest — it only removes managed guard hooks, makes the router itself explicit-only, and restores routed skills to implicit/default visibility:
Re-enable reinstalls guard hooks, reapplies explicit-only routed-skill controls, rebuilds the index, and checks preparedness:
To apply a temporary profile for high-throughput work and then return to the managed router state:
Check overall router and durable-executor status at any time:
skillspec status is read-only. It reports lifecycle state, scanned roots, index freshness, managed hook state, and SkillSpec-backed versus prose-only skills without mutating anything.