---
name: skill-router
description: >
  This skill should be used when the user has a vague or cross-domain request and
  asks "which skill should I use", "is there a skill for this", "find the right
  skill", or "route this to the best skill" — it matches an intent against the
  whole skills library and recommends the best-fit skill(s).
license: MIT + Commons Clause
metadata:
  version: 1.0.0
  author: borghei
  category: workflow
  domain: orchestration
  updated: 2026-06-22
  python-tools: route_skill.py
  tags: [router, discovery, orchestration, navigation, intent-matching]
---
# 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

```bash
# 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`.