skillspec index and route — Build and Query Skill Catalogs

skillspec index and skillspec route are the core skill-discovery primitives. index builds a local SQLite catalog from one or more harness skill roots. route scores candidate skills from that catalog against a task query and returns an authoritative routing decision. These are runtime skill discovery commands, not source analysis, workspace recon, or skill import. When the router is installed and enabled, use skillspec router index refresh instead of skillspec index directly, so visibility controls and preparedness checks run too.

`skillspec index`

Builds the local SQLite skill catalog used by skillspec route and the optional skill router. Directory paths resolve to skill-index.sqlite.

skillspec index \
  --roots <path>... \
  --out <index-file-or-router-dir> \
  [--visibility-manifest <path>] \
  [--json]

Flag	Description
`--roots <path>...`	One or more harness skill root directories to scan. Repeatable.
`--out <path>`	Output path for the SQLite index file, or a directory path that resolves to `<dir>/skill-index.sqlite`.
`--visibility-manifest <path>`	Optional visibility manifest to apply before writing the index. Overrides per-skill visibility state.
`--json`	Emit JSON report.

Running skillspec index directly prints warnings that explain router state: no installed router config means standalone manual lookup only; disabled router mode means the index will not affect implicit skill selection until skillspec router enable; enabled router mode should use skillspec router index refresh so visibility controls and preparedness checks run too.

Example

# Build a standalone index from all three standard roots
skillspec index \
  --roots ~/.agents/skills ~/.codex/skills \
  --out ~/.skillspec/router \
  --json

`skillspec route`

Scores candidate skills from the index and returns an authoritative routing decision: use_skill, bypass, or ambiguous.

skillspec route \
  --index <index-file-or-router-dir> \
  --query <text> \
  [--top <n>] \
  [--profile <name>] \
  [--execution-mode direct|durable] \
  [--current-harness agents|codex|claude-local] \
  [--current-root <path>] \
  [--json]

Flag	Description
`--index <path>`	Index file or directory path (`skill-index.sqlite` resolved from dir).
`--query <text>`	Task description to score candidates against.
`--top <n>`	Number of candidates to return (default 5).
`--profile <name>`	Named router policy profile to apply during scoring. If omitted, uses the active profile stored in SQLite.
`--execution-mode direct\|durable`	Execution mode context for the route decision. When omitted and `use_skill` is decided, an elicitation for `execution_mode_direct_or_durable` is included in the report.
`--current-harness agents\|codex\|claude-local`	Current harness identity for deduplication preference when the same logical skill is installed in multiple roots.
`--current-root <path>`	Current harness root for deduplication preference.
`--json`	Emit JSON report.

Route decisions

Decision	Meaning
`use_skill`	The selected skill path is returned. The router should load this skill.
`bypass`	No candidate was selected. The router continues normal harness behavior.
`ambiguous`	Two or more candidates are too close to separate automatically. The router continues normal behavior.

bypass and ambiguous leave selected null and include bypass_reason (no_candidates, low_confidence, ambiguous_match, no_activation_anchor, policy_passthrough).

Scoring and deduplication

Duplicate physical installs of the same logical skill are collapsed before the match gate.
--current-harness and --current-root only choose the preferred physical copy after logical selection.
Managed skill-router packages are always excluded from candidates.
If a router policy profile is active, policy can prefer, allow, suppress, or forbid generic targets (skill:<name>, tag:<tag>, source:<source>, has_skill_spec:<true|false>) before the match gate.
Output includes base_score, policy_score, policy_reason, and policy when a policy was applied.

Examples

# Query the router index
skillspec route \
  --index ~/.skillspec/router \
  --query 'extract text from a pdf' \
  --current-harness codex \
  --json

# Query with top-3 candidates and apply a named policy profile
skillspec route \
  --index ~/.skillspec/router \
  --query 'browse the dashboard and screenshot it' \
  --top 3 \
  --profile focus \
  --json

`skillspec skills` subcommands

Inspect and manage installed skills.

`skills audit`

Audits routing metadata for overlong descriptions (over 800 characters), vague descriptions, missing negative boundaries, and duplicate names.

skillspec skills audit --roots <path>... [--json]

skillspec skills audit --roots ~/.agents/skills --json

`skills set-visibility`

Sets one skill’s conceptual visibility using native Codex/Claude controls and records a reversible manifest.

skillspec skills set-visibility <skill> <implicit|manual-only|name-only|off> \
  --roots <path>... \
  --manifest <path> \
  [--dry-run] \
  [--json]

skillspec skills set-visibility pdf manual-only \
  --roots ~/.agents/skills \
  --manifest ~/.skillspec/router/visibility-manifest.json

`skills disable` / `skills enable`

Convenience wrappers for set-visibility.

skillspec skills disable <skill> --roots <path>... --manifest <path> [--dry-run] [--json]
skillspec skills enable <skill> --roots <path>... --manifest <path> [--dry-run] [--json]

disable sets the skill to off (excluded from router results when the manifest is used).
enable sets the skill to implicit.

skillspec skills disable legacy-skill \
  --roots ~/.agents/skills \
  --manifest ~/.skillspec/router/visibility-manifest.json

To understand why a query routes or does not route to a skill, use skillspec router policy explain --query <text> — it returns the full route report with matched policy rules and score changes.

skillspec router index refresh — Rebuild the index with router-managed visibility controls applied.
skillspec router index status — Check for new, changed, or missing skills in the index.
skillspec route — Query the catalog after building the index.
skillspec visibility plan/apply/restore — Manage harness-native visibility independently.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec index and route — Build and Query Skill Catalogs

`skillspec index`

Example

`skillspec route`

Route decisions

Scoring and deduplication

Examples

`skillspec skills` subcommands

`skills audit`

`skills set-visibility`

`skills disable` / `skills enable`

​skillspec index

​Example

​skillspec route

​Route decisions

​Scoring and deduplication

​Examples

​skillspec skills subcommands

​skills audit

​skills set-visibility

​skills disable / skills enable

​Related commands

`skillspec index`

Example

`skillspec route`

Route decisions

Scoring and deduplication

Examples

`skillspec skills` subcommands

`skills audit`

`skills set-visibility`

`skills disable` / `skills enable`

Related commands