Activate once per session to route substantive requests to the right installed skill. Two modes: suggest (interactive, ranked proposals) or auto (silent with attribution footer). Trigger: /skill-router on | /skill-router on --auto | /skill-router status
Install via CLI
openskills install pcx-wave/skill-router---
name: skill-router
description: >
Activate once per session to route substantive requests to the right installed skill.
Two modes: suggest (interactive, ranked proposals) or auto (silent with attribution footer).
Trigger: /skill-router on | /skill-router on --auto | /skill-router status
version: 1.2.0
license: MIT
user-invocable: true
allowed-tools:
- Bash
- Read
---
# Skill Router
## Purpose
Scan all installed skills once, build a lightweight in-session index, then route
subsequent requests to the most relevant skill — but only when a skill would
materially improve the response. No overhead on conversational or trivial requests.
Two modes:
- **Suggest mode** (default): proposes matching skills ranked by relevance, waits for confirmation
- **Auto mode**: routes silently and appends `*(via skill-name)*` to routed responses
---
## Activation
### `/skill-router on` — suggest mode (default)
### `/skill-router on --auto` — auto mode
Both run the same activation steps:
### Step 1 — Scan installed skills
```bash
find ~/.claude/skills -name "SKILL.md" | sort
```
For each file found, extract the following fields (in order of preference):
1. `name:` from YAML frontmatter
2. `description:` from YAML frontmatter
3. `triggers:` or `trigger:` from YAML frontmatter (if present)
4. If any field is missing, infer it from the first 20 lines of the file
Skip `skill-router` itself. Skip files that cannot be read.
### Step 2 — Build the index
Construct an in-memory table (session-only, never written to disk):
```
SKILL INDEX
-----------
<skill-name> | <trigger keywords, comma-separated> | <one-line description>
...
```
Also initialize an in-memory **session usage counter**:
```
SESSION_USAGE = {} ← empty dict, incremented each time a skill is invoked
```
Example row:
```
geo-audit | geo, seo, audit, AI search | Full website GEO+SEO audit with parallel subagent delegation.
```
Rules:
- Extract trigger keywords from the `trigger`, `triggers`, or `tags` frontmatter fields
- If none exist, infer 3–5 keywords from the description and first 20 lines
- Keep the total index under 1000 tokens — truncate descriptions aggressively, not skill names
- Group similar skills mentally (e.g. all `geo-*` skills = "GEO/SEO domain")
### Index quality
The router reads only frontmatter + first 20 lines of each `SKILL.md` at activation time — NOT the full content. Full `SKILL.md` content is only loaded when a skill is actually selected for routing. This means routing quality depends directly on the quality of each installed skill's frontmatter.
The fields that matter most:
- `description:` — most important. Use verb-first phrasing with concrete keywords.
- `tags:` — explicit keyword list for matching.
- `trigger:` / `triggers:` — alternative keyword sources.
Good frontmatter example:
```yaml
description: "Run a full GEO audit on a website — crawlability, schema, content quality, AI citability"
tags: [geo, seo, audit, AI search]
```
Bad frontmatter example:
```yaml
description: "A useful skill for various tasks"
```
Tip: if an expected skill is not triggering, check its frontmatter first.
### Step 3 — Confirm activation
If the scan returns zero SKILL.md files, reply:
```
Skill Router: no skills found at ~/.claude/skills. Install skills first.
```
and do not activate routing.
Otherwise, reply with exactly one line:
```
Skill Router active [suggest | auto] — <N> skills indexed (<domain1>, <domain2>, ...).
```
Examples of domains: GEO/SEO, Testing, Deployment, Git, Security, Code Review, AI Delegation.
List at most 5 domain labels. Nothing else.
---
### `/skill-router off`
Reply with exactly one line: `Skill Router off.`
All subsequent requests are answered directly — no routing until `/skill-router on` is run again.
---
## Behavior after activation
> **Lifecycle note:** routing state lives in conversation context. In very long sessions,
> context compression may truncate earlier turns and silently deactivate routing.
> If you notice routing has stopped, re-run `/skill-router on` to re-activate.
For **every subsequent user input**, first apply the gate check:
```
1. Is the request conversational, a simple question, or under ~10 words?
→ Answer directly. Do NOT load any skill.
2. Is it a substantive task (feature, audit, workflow, architecture, etc.)?
→ Scan the index. Identify all skills with HIGH confidence match.
→ Branch based on active mode (see below).
3. No HIGH confidence match?
→ Answer directly from your own knowledge. Do NOT mention any skill.
```
**HIGH confidence** = clear keyword overlap, not just tangential similarity.
```
✅ "run a GEO audit on plume.africa" → geo-audit (exact domain + action match)
✅ "write a Dockerfile for this Node app" → docker-patterns (explicit tool + task)
❌ "fix this bug in my app" → no match (too generic, no skill keyword overlap)
❌ "how do I structure my API?" → no match (tangential, answerable directly)
```
---
## Suggest mode behavior
When one or more skills match with HIGH confidence, **before answering**, show:
```
Suggested skills for this request:
1. <skill-name> — <one-line reason why it matches>
2. <skill-name> — <one-line reason why it matches> ← if a second skill also matches
Use skill 1, 2, or answer directly? (1/2/no)
```
- List at most 2 skills, ranked by relevance (most specific first)
- Wait for the user's reply before proceeding
- If user replies `1` or `2` → load that skill's SKILL.md fully, apply its rules, then **record usage** (see Usage Tracking)
- If user replies `no` or anything else → answer directly without loading any skill
- If only one skill matches, still show the prompt with just option 1
---
## Auto mode behavior
When one skill matches with HIGH confidence:
- Load that skill's SKILL.md fully, apply its rules, then **record usage** (see Usage Tracking)
- Append exactly this footer at the end of the response:
```
*(via skill-name)*
```
- No other mention of routing. No preamble. No explanation.
- If two skills match equally, prefer the **more specific** one
(e.g. `geo-schema` beats `geo` for a schema-only question)
---
## Routing rules (both modes)
- Load **at most one skill** per request
- Never load a skill for requests under ~10 words
- Never trigger `skill-router` on itself
- Never auto-trigger on `/skill-router status`
- The bar is HIGH: only trigger when the skill would **change the quality of the response**,
not just because keywords overlap
---
## Usage Tracking
Every time a skill is invoked (user confirms in suggest mode, or auto-routes), do two things:
**1. Update in-memory session counter:**
```
SESSION_USAGE[skill-name] += 1
```
**2. Persist to `~/.claude/skill-usage.json`** by running this Bash command (replace `SKILL_NAME` and `TODAY`):
```bash
python3 -c "
import json, os
f = os.path.expanduser('~/.claude/skill-usage.json')
d = json.load(open(f)) if os.path.exists(f) else {}
s = 'SKILL_NAME'
d.setdefault(s, {'total': 0, 'last_used': None})
d[s]['total'] += 1
d[s]['last_used'] = 'TODAY'
json.dump(d, open(f, 'w'), indent=2)
"
```
Where `TODAY` = current date in `YYYY-MM-DD` format (`$(date +%Y-%m-%d)`).
Run this silently — no output to user.
---
## `/skill-router stats`
Read the persistent usage file, merge with the session counter, and display:
```bash
python3 -c "
import json, os
f = os.path.expanduser('~/.claude/skill-usage.json')
print(json.dumps(json.load(open(f)), indent=2) if os.path.exists(f) else '{}')
"
```
Then display a table sorted by `total` descending, with session column overlaid from `SESSION_USAGE`:
```
Skill Usage Stats
-----------------
Skill | Total | Session | Last Used
--------------------+-------+---------+----------
geo-audit | 12 | 2 | 2026-05-15
vibe | 8 | 1 | 2026-05-18
docker-patterns | 3 | 0 | 2026-05-01
geo-schema | 0 | 0 | never
```
Rules:
- Show all skills currently in the index, even if count = 0
- Skills with `total = 0` appear at the bottom with `never` as last used date
- Sort: descending by `total`, then alphabetically within ties
- Session column shows 0 for skills not used in the current session
- After the table: `Total invocations this session: <sum of SESSION_USAGE values>`
---
## `/skill-router status`
Show exactly this, nothing more:
```
Skill Router status
-------------------
Mode: suggest | auto | off
Skills indexed: <N>
Index:
<skill-name> | <trigger domains> | <one-line description>
...
Last skill used: <skill-name> | none this session
```
If the router was never activated this session:
```
Skill Router not active. Type `/skill-router on` (suggest) or `/skill-router on --auto` to activate.
```
---
## Non-goals
- Do NOT persist the index across sessions (stateless, session-only)
- Do NOT update the index mid-session
- Do NOT load multiple skills per request
- Do NOT trigger on greetings, status checks, or clarifying questions
- Do NOT create any files during activation or routing — **except** `~/.claude/skill-usage.json` (usage tracking only)
No comments yet. Be the first to comment!