skill-router

Skill Router

Overview

This library has hundreds of skills across sixteen domains. A user rarely knows the

exact skill name — they know their intent ("I need to figure out what to build

next quarter," "I have to respond to a data breach"). The router closes that gap: it

matches a free-text request against every skill's description and tags, ranks the

candidates, and recommends the best fit — so the right skill activates on the first

try instead of the user grepping folders or guessing.

It is the user-invoked orchestrator in the two-tier model: it never does the work

itself, it routes to the skill (the discipline) that does. Treat its output as a

recommendation, then activate the chosen skill.

Use when

• Vague intent — the user describes a goal but not which skill ("help me plan a launch").
• Cross-domain ambiguity — the request could plausibly live in several domains (is "pricing" PM, finance, or business-growth?).
• Discovery — the user asks whether a skill exists for X before assuming there isn't one.
• Disambiguation — several similarly named skills exist (e.g. multiple PRD or CRO skills) and you need the closest match.

Clarify First

Before routing, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• [ ] The actual goal — the outcome the user wants, in their words (the router matches intent, so a vague goal yields vague matches)
• [ ] Artifact vs advice — do they want to produce something or decide/understand something (separates generative skills from advisory ones)

Stop rule: if the request is already specific, skip the questions and route directly.

Quick Start

# Recommend the best-fit skills for an intent
python scripts/route_skill.py "plan a go-to-market for a new B2B feature"

# Narrow to a domain, or widen the result set
python scripts/route_skill.py "respond to a data breach" --top 5
python scripts/route_skill.py "forecast revenue" --domain finance --format json

1. Run route_skill.py "<the user's goal>" against the generated catalog (cli/skills.json).
2. Review the ranked candidates and their match reasons.
3. Pick the top fit (or present the top 2-3 if genuinely ambiguous) and activate that skill — do not do the work in the router.
4. If nothing scores well, say so plainly and suggest the closest domain rather than forcing a weak match.

How matching works

The script scores each skill by term overlap between the query and the skill's

name, tags, domain, and description, weighting exact name/tag hits highest.

It reads the catalog from cli/skills.json (regenerated by scripts/build_manifest.py),

so it always reflects the current library without hardcoding any skill list.

Anti-patterns

• Doing the work instead of routing. The router recommends; the recommended skill executes. Don't blur the two.
• Forcing a match. If the top score is weak, say "no strong fit" — a confidently wrong route is worse than an honest miss.
• Ignoring the artifact-vs-advice split. Routing a "produce a PRD" intent to an advisory persona (or vice-versa) wastes the user's time.
• Hardcoding skill names. Always read the live catalog; the library changes.

Scope & Limitations

In Scope: Matching a free-text intent against the skills catalog and recommending the best-fit skill(s); disambiguating similar skills; confirming whether a skill exists for a goal.

Out of Scope: Executing the matched skill's workflow (that's the target skill's job); multi-skill workflow orchestration across a sequence (see standards/ orchestration protocol and agents/personas/); installing or extracting skills.

Dependency note: the router reads the repo-level catalog cli/skills.json. It is a navigation aid for use within the library, not a standalone single-skill download — if the catalog is absent, point the script at it with --catalog <path> or regenerate it with python scripts/build_manifest.py.

References

• scripts/route_skill.py — intent-to-skill scorer over cli/skills.json.