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.

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]
FlagDescription
--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.
--jsonEmit 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]
FlagDescription
--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|durableExecution 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-localCurrent harness identity for deduplication preference when the same logical skill is installed in multiple roots.
--current-root <path>Current harness root for deduplication preference.
--jsonEmit JSON report.

​
Route decisions

DecisionMeaning
use_skillThe selected skill path is returned. The router should load this skill.
bypassNo candidate was selected. The router continues normal harness behavior.
ambiguousTwo 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us