skillspec router — Install and Manage the Skill Router

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.

Always run 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.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec router — Install and Manage the Skill Router

Install / Update / Uninstall

`router install`

`router update`

`router uninstall`

`router enable` / `router disable`

Guard Hook

`router guard`

Index Management

`router index refresh`

`router index status`

Policy Management

`router policy init/list/show/get`

`router policy set-profile`

`router policy set-rule`

`router policy remove-rule`

`router policy explain`

`router profile status/apply/clear`

​Install / Update / Uninstall

​router install

​router update

​router uninstall

​router enable / router disable

​Guard Hook

​router guard

​Index Management

​router index refresh

​router index status

​Policy Management

​router policy init/list/show/get

​router policy set-profile

​router policy set-rule

​router policy remove-rule

​router policy explain

​router profile status/apply/clear

​Related commands

Install / Update / Uninstall

`router install`

`router update`

`router uninstall`

`router enable` / `router disable`

Guard Hook

`router guard`

Index Management

`router index refresh`

`router index status`

Policy Management

`router policy init/list/show/get`

`router policy set-profile`

`router policy set-rule`

`router policy remove-rule`

`router policy explain`

`router profile status/apply/clear`

Related commands