System Skill Advisor
Routes non-trivial user requests to the right skill through the standalone Skill Advisor package and its CLI front door.
1. WHEN TO USE
Use this skill when the work is about skill selection, Gate 2 routing, advisor CLI commands, prompt-time skill-advisor hooks, skill graph freshness or the standalone advisor package.
Activation signals:
- A request asks which skill should handle a task.
- A runtime hook needs a skill recommendation before execution.
- An operator asks about
advisor_recommend, advisor_status, advisor_rebuild, advisor_validate, skill_graph_scan, skill_graph_query, skill_graph_status, skill_graph_validate or skill_graph_propagate_enhances.
- A packet touches the skill graph, skill metadata, advisor scorer, advisor feature catalog or manual testing playbook.
Do not use this skill as a replacement for the recommended target skill. For example, route code implementation to sk-code, documentation authoring to sk-doc, git work to sk-git and MCP orchestration to mcp-code-mode after the advisor has made the recommendation.
2. SMART ROUTING
Use this skill for non-trivial Gate 2 routing or requests about advisor commands, hooks, skill graph or the package.
An exact skill name or explicit user direction takes priority.
Otherwise, use advisor_recommend through the CLI to choose a target skill.
Load that target skill before acting in its domain.
This package covers advisor routing and behavior.
For local documentation, load the leaf mapped to the detected intent.
Weak signals use fallback references. Broad browsing uses a package index.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
The advisor runs as a resident daemon with one CLI front door. The package owns the whole routing boundary, so routing can be tuned and rolled back independently.
The package owns the advisor daemon and its CLI front door, and it lists all 9 commands. The command ids stay stable:
Commands (9):
advisor_recommend
advisor_rebuild
advisor_status
advisor_validate
skill_graph_scan
skill_graph_query
skill_graph_status
skill_graph_validate
skill_graph_propagate_enhances
skill_graph_propagate_enhances is trust-gated only for real apply writes (mode=apply with dryRun not true). Report, propose and dry-run apply calls remain read-safe.
The stable command ids matter because live consumers already call them from hooks, the Python scorer, doctor workflows, scripts and CI. The package boundary supplies the isolation, so callers use the advisor without learning a new vocabulary.
The CLI is the only front door. The same 9 commands are callable through node .skilled/bin/skill-advisor.cjs <command> over the daemon's unix socket. A shim refuses to run a stale dist.
Recovery example: node .skilled/bin/skill-advisor.cjs advisor_recommend --json '{"prompt":"<request>"}' --format json --timeout-ms 3000.
Exit codes:
0: success.
1: runtime.
64: usage/schema or trusted-mutation refusal.
69: protocol/dist mismatch or stale dist.
75: retryable daemon error.
When the daemon is unreachable, the CLI answers from the local Python scorer and marks the result degraded instead of failing the call.
--format jsonl renders one complete JSON payload on one stdout line. It is not streaming JSON Lines.
Trust resolution fails closed. A call is untrusted unless --trusted or SYSTEM_SKILL_ADVISOR_CLI_TRUSTED=1 is supplied. Mutation commands therefore require the maintainer path.
Routing phrases come from graph-metadata.json. The daemon routes from each skill's graph-metadata.json using intent_signals and derived.trigger_phrases.
- The create-skill metadata CI check keeps that file aligned with the skill root.
- The
trigger_phrases and intent_signals fields in a skill's SKILL.md frontmatter are not read by any runtime routing reader.
- The local Python scorer's frontmatter cache reads only
name, description and an inline keywords value.
- Reference and asset doc frontmatter
trigger_phrases feed routing only when SPECKIT_ADVISOR_DOC_TRIGGERS=true.
- Skill authors change routing vocabulary in
graph-metadata.json.
advisor_status reports indexStaleness on every successful call and, with includeEmbeddingsHealth, an opt-in embeddingsHealth covering provider resolution and the local model server.
The advisor implementation, skill-graph library and package-local database live under this skill package, while memory remains focused on memory tools.
Skill lifecycle: how a new skill becomes routable.
- The daemon watcher monitors the skills root itself. It watches that root shallowly, covering top-level directories only. It also watches each known root's identity files.
- When a skill is created while the daemon is warm, the new directory's event goes through the normal debounce into reindex.
- Reindex promotes the root's
SKILL.md, ROUTER.md and graph-metadata.json into durable watch targets.
The other paths:
- With no daemon running, the next daemon start ingests the skill through normal discovery.
- Refresh manually at any time with
node .skilled/bin/skill-advisor.cjs skill_graph_scan --trusted.
- Deleting a root retires its targets through the same path.
The authoring-side counterpart (routing-evidence quality and the discovery smoke test) lives in the create-skill workflows.
4. RULES
ALWAYS
- Treat
references/runtime/cli-front-door-contract.md as the source of truth for command ids, output shape and exit codes.
- Keep the advisor database under
.skilled/skills/system-skill-advisor/runtime/database/.
- Keep public advisor and skill graph command ids stable unless a later ADR explicitly changes them.
- Preserve prompt-safety boundaries. Advisor metadata and lane attribution must not echo raw prompt text.
- Keep
runtime/lib/skill-graph/ package-local to system-skill-advisor.
NEVER
- Store
skill-graph.sqlite outside this package. The database is package-local.
- Let any other runtime or server write the advisor SQLite database.
- Rename
advisor_* or skill_graph_* public commands as part of documentation work.
- Move
runtime/lib/skill-graph/ during a doc-only pass.
ESCALATE IF
- A caller requires renamed public tools.
- The standalone advisor cannot build without a broader shared-runtime extraction.
- Any migration step would create competing writers for
skill-graph.sqlite.
5. REFERENCES
Primary contract:
references/runtime/cli-front-door-contract.md: command ids, output envelope, exit taxonomy and caller obligations.
Package references:
references/scoring/advisor-scorer.md: lane attribution, fusion and confidence calibration.
references/scoring/lane-weight-tuning.md: measured lane-weight change workflow.
references/scoring/validation-baselines.md: advisor_validate baselines and troubleshooting.
references/graph/skill-graph-query-cookbook.md: worked skill_graph_query examples.
references/graph/skill-graph-drift.md: detect and reconcile SQLite drift from source files.
references/graph/skill-graph-extraction-plan.md: extraction history and completion record.
references/graph/propagate-enhances.md: internal enhances propagation contract.
references/runtime/standalone-mcp-shape.md: ADR-001 topology record (historical).
references/runtime/tool-ids-reference.md: stable public and internal tool ids.
references/runtime/legacy-tool-bridge.md: historical bridge policy record.
references/runtime/freshness-contract.md: trust-state vocabulary and caller obligations.
references/runtime/daemon-lease-contract.md: single-writer daemon lease behavior.
references/config/db-path-policy.md: package-local SQLite path policy.
hooks/skill-advisor-hook.md: prompt-time hook behavior.
references/decisions/deferred-decisions.md: Tier D decision records (F6 deprecation banners).
ARCHITECTURE.md
runtime/README.md
runtime/tools/README.md
6. SUCCESS CRITERIA
This skill is healthy when:
SKILL.md frontmatter and graph-metadata.json parse cleanly.
- Skill discovery sees
system-skill-advisor as a first-class critical system skill.
- Advisor routing requests resolve to this package without displacing target execution skills such as
sk-code, sk-doc or system-spec-kit.
advisor_* and skill_graph_* public ids remain documented as stable.
- The package-local database path is documented consistently.
7. INTEGRATION POINTS
Current package state:
- The advisor daemon and its CLI front door are owned by this package.
- Advisor handlers, schemas, tools, scripts, tests, docs and database path ownership live under this package.
skill_graph_* handlers and command descriptors live under this package.
lib/skill-graph/ database/query logic is fully migrated to system-skill-advisor (extraction complete).
Expected consumers:
- Prompt-time adapters for Claude, Codex, Cursor and Devin live under
.skilled/skills/system-spec-kit/runtime/hooks/. Pi and the OpenCode plugin (.opencode/plugins/system-skill-advisor.js) resolve the same brief builder. The plugin invokes node .skilled/bin/skill-advisor.cjs directly.
- CLI callers that run
advisor_recommend, advisor_status, advisor_rebuild, advisor_validate, skill_graph_scan, skill_graph_query, skill_graph_status, skill_graph_validate or skill_graph_propagate_enhances.
- Daemon-backed CLI callers (
node .skilled/bin/skill-advisor.cjs <command>) for doctor routes, scripts and CI, untrusted by default with --trusted for maintainer mutations.
- Doctor workflows that validate advisor health and rebuild state.
- Skill graph indexers and routing accuracy checks.
8. REFERENCES AND RELATED RESOURCES
Related skills:
system-spec-kit owns spec folders, memory, validation and packet governance.
sk-doc owns skill documentation, feature catalogs and playbooks.
Its create-skill packet also owns the skill-root metadata contract, graph-metadata template and leaf-manifest config template used by this root.
sk-code owns implementation once routing selects a code surface.
mcp-code-mode owns external MCP orchestration workflows.
The advisor should recommend these skills. It should not absorb their implementation rules.
1---2name: system-skill-advisor3description: Routes non-trivial requests to matching skills through the daemon-backed advisor CLI and stable advisor command ids.4allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]5version: 1.0.0.06trigger_phrases:7 - "skill advisor"8 - "gate 2 routing"9 - "advisor_recommend"10 - "advisor_status"11 - "which skill should handle this"12 - "route this request to a skill"13 - "system skill advisor"14keywords:15 - skill-routing16 - gate-217 - advisor-cli18 - legacy-tool-bridge19 - skill-graph20 - semantic-lane21intent_signals:22 - "Gate 2 skill routing"23 - "advisor_recommend CLI routing"24 - "advisor_status freshness check"25 - "which skill should handle this request"26 - "run the skill advisor hook"27metadata:28 source: https://skillmd.com/skills/michelkerkmeester/system-skill-advisor29---3031<!-- Keywords: system-skill-advisor, skill-advisor, advisor_recommend, advisor_status, advisor_rebuild, advisor_validate, skill_graph_scan, skill_graph_query, skill_graph_status, skill_graph_validate, skill_graph_propagate_enhances, cross-skill-edges, gate-2-routing, cli-front-door, daemon-cli, legacy-tool-bridge, skill-graph, pi prompt advisor, prompt-time brief, skill advice before the agent handles my prompt, advisor skipped my prompt, advisor skip my prompt -->3233# System Skill Advisor3435Routes non-trivial user requests to the right skill through the standalone Skill Advisor package and its CLI front door.3637---3839## 1. WHEN TO USE4041Use this skill when the work is about skill selection, Gate 2 routing, advisor CLI commands, prompt-time skill-advisor hooks, skill graph freshness or the standalone advisor package.4243Activation signals:4445- A request asks which skill should handle a task.46- A runtime hook needs a skill recommendation before execution.47- An operator asks about `advisor_recommend`, `advisor_status`, `advisor_rebuild`, `advisor_validate`, `skill_graph_scan`, `skill_graph_query`, `skill_graph_status`, `skill_graph_validate` or `skill_graph_propagate_enhances`.48- A packet touches the skill graph, skill metadata, advisor scorer, advisor feature catalog or manual testing playbook.4950Do not use this skill as a replacement for the recommended target skill. For example, route code implementation to `sk-code`, documentation authoring to `sk-doc`, git work to `sk-git` and MCP orchestration to `mcp-code-mode` after the advisor has made the recommendation.5152---5354## 2. SMART ROUTING5556Use this skill for non-trivial Gate 2 routing or requests about advisor commands, hooks, skill graph or the package.57An exact skill name or explicit user direction takes priority.58Otherwise, use `advisor_recommend` through the CLI to choose a target skill.59Load that target skill before acting in its domain.60This package covers advisor routing and behavior.61For local documentation, load the leaf mapped to the detected intent.62Weak signals use fallback references. Broad browsing uses a package index.63Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.6465---6667## 3. HOW IT WORKS6869The advisor runs as a resident daemon with one CLI front door. The package owns the whole routing boundary, so routing can be tuned and rolled back independently.7071The package owns the advisor daemon and its CLI front door, and it lists all **9 commands**. The command ids stay stable:7273Commands (9):7475- `advisor_recommend`76- `advisor_rebuild`77- `advisor_status`78- `advisor_validate`79- `skill_graph_scan`80- `skill_graph_query`81- `skill_graph_status`82- `skill_graph_validate`83- `skill_graph_propagate_enhances`8485`skill_graph_propagate_enhances` is trust-gated only for real apply writes (`mode=apply` with `dryRun` not `true`). Report, propose and dry-run apply calls remain read-safe.8687The stable command ids matter because live consumers already call them from hooks, the Python scorer, doctor workflows, scripts and CI. The package boundary supplies the isolation, so callers use the advisor without learning a new vocabulary.8889The CLI is the only front door. The same 9 commands are callable through `node .skilled/bin/skill-advisor.cjs <command>` over the daemon's unix socket. A shim refuses to run a stale dist.90Recovery example: `node .skilled/bin/skill-advisor.cjs advisor_recommend --json '{"prompt":"<request>"}' --format json --timeout-ms 3000`.91Exit codes:92- `0`: success.93- `1`: runtime.94- `64`: usage/schema or trusted-mutation refusal.95- `69`: protocol/dist mismatch or stale dist.96- `75`: retryable daemon error.9798- When the daemon is unreachable, the CLI answers from the local Python scorer and marks the result degraded instead of failing the call.99- `--format jsonl` renders one complete JSON payload on one stdout line. It is not streaming JSON Lines.100- Trust resolution fails closed. A call is untrusted unless `--trusted` or `SYSTEM_SKILL_ADVISOR_CLI_TRUSTED=1` is supplied. Mutation commands therefore require the maintainer path.101102**Routing phrases come from `graph-metadata.json`.** The daemon routes from each skill's `graph-metadata.json` using `intent_signals` and `derived.trigger_phrases`.103104- The create-skill metadata CI check keeps that file aligned with the skill root.105- The `trigger_phrases` and `intent_signals` fields in a skill's `SKILL.md` frontmatter are not read by any runtime routing reader.106- The local Python scorer's frontmatter cache reads only `name`, `description` and an inline `keywords` value.107- Reference and asset doc frontmatter `trigger_phrases` feed routing only when `SPECKIT_ADVISOR_DOC_TRIGGERS=true`.108- Skill authors change routing vocabulary in `graph-metadata.json`.109110`advisor_status` reports `indexStaleness` on every successful call and, with `includeEmbeddingsHealth`, an opt-in `embeddingsHealth` covering provider resolution and the local model server.111112The advisor implementation, skill-graph library and package-local database live under this skill package, while memory remains focused on memory tools.113114**Skill lifecycle: how a new skill becomes routable.**1151161. The daemon watcher monitors the skills root itself. It watches that root shallowly, covering top-level directories only. It also watches each known root's identity files.1172. When a skill is created while the daemon is warm, the new directory's event goes through the normal debounce into reindex.1183. Reindex promotes the root's `SKILL.md`, `ROUTER.md` and `graph-metadata.json` into durable watch targets.119120The other paths:121122- With no daemon running, the next daemon start ingests the skill through normal discovery.123- Refresh manually at any time with `node .skilled/bin/skill-advisor.cjs skill_graph_scan --trusted`.124- Deleting a root retires its targets through the same path.125126The authoring-side counterpart (routing-evidence quality and the discovery smoke test) lives in the create-skill workflows.127128---129130## 4. RULES131132### ALWAYS133134- Treat `references/runtime/cli-front-door-contract.md` as the source of truth for command ids, output shape and exit codes.135- Keep the advisor database under `.skilled/skills/system-skill-advisor/runtime/database/`.136- Keep public advisor and skill graph command ids stable unless a later ADR explicitly changes them.137- Preserve prompt-safety boundaries. Advisor metadata and lane attribution must not echo raw prompt text.138- Keep `runtime/lib/skill-graph/` package-local to `system-skill-advisor`.139140### NEVER141142- Store `skill-graph.sqlite` outside this package. The database is package-local.143- Let any other runtime or server write the advisor SQLite database.144- Rename `advisor_*` or `skill_graph_*` public commands as part of documentation work.145- Move `runtime/lib/skill-graph/` during a doc-only pass.146147### ESCALATE IF148149- A caller requires renamed public tools.150- The standalone advisor cannot build without a broader shared-runtime extraction.151- Any migration step would create competing writers for `skill-graph.sqlite`.152153---154155## 5. REFERENCES156157Primary contract:158159- [`references/runtime/cli-front-door-contract.md`](references/runtime/cli-front-door-contract.md): command ids, output envelope, exit taxonomy and caller obligations.160161Package references:162163- [`references/scoring/advisor-scorer.md`](references/scoring/advisor-scorer.md): lane attribution, fusion and confidence calibration.164- [`references/scoring/lane-weight-tuning.md`](references/scoring/lane-weight-tuning.md): measured lane-weight change workflow.165- [`references/scoring/validation-baselines.md`](references/scoring/validation-baselines.md): `advisor_validate` baselines and troubleshooting.166- [`references/graph/skill-graph-query-cookbook.md`](references/graph/skill-graph-query-cookbook.md): worked `skill_graph_query` examples.167- [`references/graph/skill-graph-drift.md`](references/graph/skill-graph-drift.md): detect and reconcile SQLite drift from source files.168- [`references/graph/skill-graph-extraction-plan.md`](references/graph/skill-graph-extraction-plan.md): extraction history and completion record.169- [`references/graph/propagate-enhances.md`](references/graph/propagate-enhances.md): internal `enhances` propagation contract.170- [`references/runtime/standalone-mcp-shape.md`](references/runtime/standalone-mcp-shape.md): ADR-001 topology record (historical).171- [`references/runtime/tool-ids-reference.md`](references/runtime/tool-ids-reference.md): stable public and internal tool ids.172- [`references/runtime/legacy-tool-bridge.md`](references/runtime/legacy-tool-bridge.md): historical bridge policy record.173- [`references/runtime/freshness-contract.md`](references/runtime/freshness-contract.md): trust-state vocabulary and caller obligations.174- [`references/runtime/daemon-lease-contract.md`](references/runtime/daemon-lease-contract.md): single-writer daemon lease behavior.175- [`references/config/db-path-policy.md`](references/config/db-path-policy.md): package-local SQLite path policy.176- [`hooks/skill-advisor-hook.md`](hooks/skill-advisor-hook.md): prompt-time hook behavior.177- [`references/decisions/deferred-decisions.md`](references/decisions/deferred-decisions.md): Tier D decision records (F6 deprecation banners).178- [`ARCHITECTURE.md`](ARCHITECTURE.md)179- [`runtime/README.md`](runtime/README.md)180- [`runtime/tools/README.md`](runtime/tools/README.md)181182---183184## 6. SUCCESS CRITERIA185186This skill is healthy when:187188- `SKILL.md` frontmatter and `graph-metadata.json` parse cleanly.189- Skill discovery sees `system-skill-advisor` as a first-class critical system skill.190- Advisor routing requests resolve to this package without displacing target execution skills such as `sk-code`, `sk-doc` or `system-spec-kit`.191- `advisor_*` and `skill_graph_*` public ids remain documented as stable.192- The package-local database path is documented consistently.193194---195196## 7. INTEGRATION POINTS197198Current package state:199200- The advisor daemon and its CLI front door are owned by this package.201- Advisor handlers, schemas, tools, scripts, tests, docs and database path ownership live under this package.202- `skill_graph_*` handlers and command descriptors live under this package.203- `lib/skill-graph/` database/query logic is fully migrated to `system-skill-advisor` (extraction complete).204205Expected consumers:206207- Prompt-time adapters for Claude, Codex, Cursor and Devin live under `.skilled/skills/system-spec-kit/runtime/hooks/`. Pi and the OpenCode plugin (`.opencode/plugins/system-skill-advisor.js`) resolve the same brief builder. The plugin invokes `node .skilled/bin/skill-advisor.cjs` directly.208- CLI callers that run `advisor_recommend`, `advisor_status`, `advisor_rebuild`, `advisor_validate`, `skill_graph_scan`, `skill_graph_query`, `skill_graph_status`, `skill_graph_validate` or `skill_graph_propagate_enhances`.209- Daemon-backed CLI callers (`node .skilled/bin/skill-advisor.cjs <command>`) for doctor routes, scripts and CI, untrusted by default with `--trusted` for maintainer mutations.210- Doctor workflows that validate advisor health and rebuild state.211- Skill graph indexers and routing accuracy checks.212213---214215## 8. REFERENCES AND RELATED RESOURCES216217Related skills:218219- `system-spec-kit` owns spec folders, memory, validation and packet governance.220- `sk-doc` owns skill documentation, feature catalogs and playbooks.221 Its `create-skill` packet also owns the [skill-root metadata contract](../sk-doc/sk-create-skill/references/shared/skill-root-metadata-contract.md), [graph-metadata template](../sk-doc/sk-create-skill/assets/skill/skill-graph-metadata-template.json) and [leaf-manifest config template](../sk-doc/sk-create-skill/assets/skill/skill-leaf-manifest-config-template.json) used by this root.222- `sk-code` owns implementation once routing selects a code surface.223- `mcp-code-mode` owns external MCP orchestration workflows.224225The advisor should recommend these skills. It should not absorb their implementation rules.