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.
skillspec router installs and manages the SkillSpec-backed skill-router skill, which enables large skill catalogs without putting every skill description into the model context. The router intercepts agent requests, scores candidates from a local SQLite index, and loads a skill only when the route decision is use_skill. bypass and ambiguous decisions continue normal harness behavior.
Install / Update / Uninstall
router install
Installs the skill-router skill, enables router mode, installs managed Codex/Claude prompt guard hooks, makes routed skills explicit-only, builds the index, checks post-index preparedness, and writes router config.
skillspec router install \
--roots <path>... \
--index <index-file-or-router-dir> \
[--manifest <path>] \
[--router-name <name>] \
[--dry-run] \
[--force] \
[--json]
| Flag | Description |
|---|
--roots <path>... | Harness skill roots to manage. Required. Repeatable. |
--index <path> | Index file path or router directory. Required. Directory paths resolve to skill-index.sqlite. |
--manifest <path> | Path for the reversible visibility manifest. |
--router-name <name> | Custom name for the router skill folder. |
--dry-run | Report planned writes without executing. |
--force | If the router config directory path already exists as a legacy SQLite index file, migrate that file to <router-dir>/skill-index.sqlite before writing config. |
--json | Emit JSON report. |
skillspec router install \
--roots ~/.agents/skills \
--index ~/.skillspec/router \
--json
router update
Backs up the router config, manifest, index, and managed router skill directories, rewrites the SkillSpec-backed router package in every recorded harness root, preserves enabled/disabled mode, refreshes managed guard hooks, reapplies matching visibility, and rebuilds the index only when enabled.
skillspec router update [--backup-dir <path>] [--dry-run] [--json]
skillspec router update --json
router uninstall
Restores visibility from the manifest, removes managed router guard hook entries, removes every managed router skill marker directory recorded by router config, removes config, and optionally removes the index.
skillspec router uninstall \
[--manifest <path>] \
[--index <path>] \
[--keep-index] \
[--dry-run] \
[--json]
--keep-index preserves the SQLite skill catalog after uninstall. Alias: router delete.
skillspec router uninstall --keep-index --json
router enable / router disable
skillspec router enable [--dry-run] [--json]
skillspec router disable [--dry-run] [--json]
enable re-enables an installed router: refreshes managed files, installs guard hooks, makes routed skills explicit-only, rebuilds the index, checks preparedness, and warns to restart harnesses.
disable keeps the router installed but removes only managed guard hook entries, makes the router itself explicit-only, restores routed skills to implicit/default visibility, and writes enabled: false.
Guard Hook
router guard
Verifies router-first readiness from router config. When enabled and stale/missing index state is detected, reapplies router-managed visibility and rebuilds the index before reporting first_hop_ready.
skillspec router guard \
[--config <path>] \
[--hook] \
[--harness agents|codex|claude-local] \
[--json]
| Flag | Description |
|---|
--config <path> | Explicit router config path. |
--hook | Emit native UserPromptSubmit hook JSON. Success injects compact router-ready context; failure blocks with a repair command. |
--harness agents|codex|claude-local | Identify the invoking harness for context injection. |
--json | Emit JSON report (without --hook). |
skillspec router guard --hook --harness codex
Index Management
router index refresh
Repairs router-managed state after skill additions, removals, or metadata changes. When router config is present and enabled, reapplies explicit-only native controls across roots (preserving an enabled durable-executor as implicit), rebuilds the index, and reports preparedness.
skillspec router index refresh \
--roots <path>... \
--index <path> \
[--visibility-manifest <path>] \
[--json]
skillspec router index refresh \
--roots ~/.agents/skills \
--index ~/.skillspec/router \
--visibility-manifest ~/.skillspec/router/visibility-manifest.json
router index status
Compares the index against current roots and reports new, changed, missing, stale, and updated-at state. New and changed entries include whether they are prose-only or SkillSpec-backed. Prose-only entries include conversion advice.
skillspec router index status \
--roots <path>... \
--index <path> \
[--visibility-manifest <path>] \
[--json]
skillspec router index status \
--roots ~/.agents/skills \
--index ~/.skillspec/router \
--json
Policy Management
Router policy is stored in the same SQLite database as the skill catalog. Policies are local, auditable, and provider-neutral.
router policy init/list/show/get
skillspec router policy init --index <path> [--json]
skillspec router policy list --index <path> [--json]
skillspec router policy show --index <path> [--profile <name>] [--json]
skillspec router policy get <id> --index <path> [--json]
get returns one profile or rule by ID. Use it before editing a preference policy so existing predicates, order, and targets are preserved.
skillspec router policy get browser_work \
--index ~/.skillspec/router \
--json
router policy set-profile
Creates or updates a routing profile.
skillspec router policy set-profile <name> \
--index <path> \
--mode route|soft-passthrough|native-passthrough \
[--active] \
[--strict] \
[--description <text>] \
[--json]
| Mode | Behavior |
|---|
route | Normal router behavior with policy preferences applied. |
soft-passthrough | Bypass by default unless a matching rule allows or prefers a candidate. |
native-passthrough | Intended high-throughput mode; current route-time behavior is soft passthrough until lifecycle visibility mutation is implemented. |
--active sets the profile as the active policy profile. --strict makes policy rules the only gate (no fallback to base routing).
skillspec router policy set-profile code \
--index ~/.skillspec/router \
--mode soft-passthrough \
--active \
--json
router policy set-rule
Creates or replaces a preference rule.
skillspec router policy set-rule <id> \
--index <path> \
--profile <name> \
--priority <n> \
[--mode soft|hard] \
[--anchor none|policy] \
[--when-any <phrase>...] \
[--when-all <phrase>...] \
[--when-none <phrase>...] \
[--prefer skill:<name>|tag:<tag>|source:<source>|has_skill_spec:<true|false>] \
[--allow ...] \
[--suppress ...] \
[--forbid ...] \
[--json]
| Flag | Description |
|---|
--priority <n> | Rule priority; higher numbers evaluated first. |
--mode soft|hard | Soft rules are advisory; hard rules block conflicting candidates. |
--anchor none|policy | anchor policy lets an exact skill:<name> preference satisfy the activation-anchor gate. |
--when-any / --when-all / --when-none | Predicate phrases. Repeatable. |
--prefer / --allow / --suppress / --forbid | Preference targets. Format: skill:<name>, tag:<tag>, source:<source>, has_skill_spec:<true|false>. Repeatable. |
policy get <id> before editing an existing rule to preserve existing predicates.
skillspec router policy set-rule browser_work \
--index ~/.skillspec/router \
--profile default \
--priority 100 \
--anchor policy \
--when-any browse \
--prefer skill:browser \
--json
router policy remove-rule
skillspec router policy remove-rule <id> --index <path> [--json]
skillspec router policy remove-rule browser_work \
--index ~/.skillspec/router \
--json
router policy explain
Runs the router with the named or active profile and returns the same route report with matched policy rules and score changes.
skillspec router policy explain \
--index <path> \
--query <text> \
[--profile <name>] \
[--top <n>] \
[--json]
skillspec router policy explain \
--index ~/.skillspec/router \
--profile default \
--query 'browse the dashboard' \
--json
router profile status/apply/clear
Shows, activates, or clears the active router policy profile in SQLite.
skillspec router profile status --index <path> [--json]
skillspec router profile apply <profile> --index <path> [--dry-run] [--json]
skillspec router profile clear --index <path> [--dry-run] [--json]
skillspec router profile apply code --index ~/.skillspec/router --json
After any router operation that changes the skill set or visibility, restart active harness sessions so the updated router skill and index take effect.
skillspec index — Build a standalone SQLite skill catalog.skillspec route — Query the skill catalog for a given task.skillspec visibility plan/apply/restore — Manage harness-native skill visibility independently of the router.skillspec status — View router, durable-executor, and skill installation state.
