Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt

Use this file to discover all available pages before exploring further.

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:
DecisionMeaning
use_skillThe top candidate has high confidence and clears the separation threshold; load the selected SKILL.md
bypassNo positive candidate exists, or the best candidate lacks an activation anchor; continue normal agent behavior
ambiguousTwo strong candidates are too close for automatic selection; do not silently load either
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. 
skillspec router install \
  --roots ~/.agents/skills \
  --index ~/.skillspec/router \
  --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: 
skillspec index \
  --roots ~/.agents/skills \
  --out ~/.skillspec/router \
  --json
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: 
skillspec route \
  --index ~/.skillspec/router \
  --query 'browse gmail' \
  --current-harness codex \
  --top 5 \
  --json
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. 
skillspec router guard \
  --config ~/.skillspec/router/config.json \
  --hook \
  --harness codex
In diagnostic mode (without --hook), the guard reports first_hop_ready, index status before and after any repair, and any visibility repair output: 
skillspec router guard --json
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

skillspec router policy set-profile code \
  --index ~/.skillspec/router \
  --mode soft-passthrough \
  --active \
  --json
--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

skillspec router policy set-rule browser_work \
  --index ~/.skillspec/router \
  --profile default \
  --priority 100 \
  --when-any browse \
  --when-any dashboard \
  --when-any authenticated \
  --prefer skill:browser \
  --anchor policy \
  --json
--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

skillspec router policy get browser_work \
  --index ~/.skillspec/router \
  --json
Always run policy get or policy show before editing an existing rule so you preserve existing predicates and preferences.
4

Explain a routing decision

skillspec router policy explain \
  --index ~/.skillspec/router \
  --profile default \
  --query 'browse the dashboard' \
  --json
The explanation includes base_score, policy_score, policy_reason, and which rules matched, so you can audit exactly why a candidate was selected.
# Initialize and inspect policy tables
skillspec router policy init --index ~/.skillspec/router --json
skillspec router policy list --index ~/.skillspec/router --json
skillspec router policy show --index ~/.skillspec/router --profile default --json
skillspec router policy get browser_work --index ~/.skillspec/router --json

# Create or update profiles and rules
skillspec router policy set-profile code \
  --index ~/.skillspec/router \
  --mode soft-passthrough \
  --active --json

skillspec router policy set-rule browser_work \
  --index ~/.skillspec/router \
  --profile default \
  --priority 100 \
  --when-any browse --when-any dashboard \
  --prefer skill:browser --anchor policy --json

# Remove a rule
skillspec router policy remove-rule browser_work \
  --index ~/.skillspec/router --json

# Explain a route decision under a named profile
skillspec router policy explain \
  --index ~/.skillspec/router \
  --query 'browse the dashboard' --json

​
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: 
skillspec router index refresh \
  --roots ~/.agents/skills \
  --index ~/.skillspec/router \
  --json
For a read-only view of what has drifted before refreshing: 
skillspec router index status \
  --roots ~/.agents/skills \
  --index ~/.skillspec/router \
  --json
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: 
skillspec router disable --json
Re-enable reinstalls guard hooks, reapplies explicit-only routed-skill controls, rebuilds the index, and checks preparedness: 
skillspec router enable --json
To apply a temporary profile for high-throughput work and then return to the managed router state: 
# Apply a native-passthrough focus profile
skillspec router profile apply code --index ~/.skillspec/router --json

# Return to router-managed state
skillspec router profile clear --index ~/.skillspec/router --json
Check overall router and durable-executor status at any time: 
skillspec status --json
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us