octaviantocan router
A meta-skill that helps you navigate your own skill library. It tracks which
skills you actually invoke (via a PostToolUse hook into a local SQLite DB),
ranks candidate skills for a request, and chains skills into named, declarative
workflows the way superpowers chains brainstorming → planning → execution.
Variables
- DB_PATH:
<skill-dir>/data/usage.dbby default — the script resolves its own install location via__file__, so the DB lives wherever the skill is installed. Override with theROUTER_DBenv var. - CLI:
python3 <skill-dir>/scripts/router.py <subcommand>(stdlib only) - WORKFLOWS_DIR:
<skill-dir>/workflows/— resolved at runtime; one*.mdper workflow. - HOOK_SETTINGS:
$HOME/.claude/settings.jsonby default; override with--settingsoninstall-hook.
The default install location is $HOME/.claude/skills/router/ (see README).
If you install elsewhere, swap that path into the commands above.
How It Works
A PostToolUse hook on the Skill tool logs every skill invocation (name, args,
session, timestamp) into SQLite. stats aggregates that log; pick blends
lexical relevance + usage frequency + recency into a shortlist that you choose
from; workflows are declarative markdown files the agent walks step by step,
announcing each handoff.
install-hook embeds the absolute path to the script at install time, so
the hook works no matter where the skill is installed.
Arguments
Invoke as /router <command> [arguments]. Parse the text after /router:
the first whitespace-delimited token is the command; everything after it is
that command's arguments (free text and/or --flags). --flags pass
straight through to the CLI.
| Invocation | Command | Arguments |
|---|---|---|
/router stats [--days N] [--limit N] |
stats | optional window + cap |
/router pick <request> |
pick | free-text task description (required) |
/router run <workflow> |
run | a workflow name from /router workflows |
/router workflows |
workflows | none |
/router setup |
setup | none |
Defaults & aliases (apply before dispatching):
- No command but free text follows (e.g.
/router fix a flaky test) → treat the whole thing aspick <that text>. - No command and no text → show this Arguments table and stop.
- Aliases:
top/most-used/usage→stats;recommend/choose/which→pick;list→workflows. - Unrecognized command → show the table and ask which they meant; do not guess.
Once the command and arguments are parsed, read the matching cookbook file, then execute it with those arguments.
Commands
| Command | Purpose |
|---|---|
/router setup |
Install the usage hook + initialize the SQLite DB |
/router stats |
List your most-used skills (all-time or a recent window) |
/router pick <request> |
Recommend the best-fit skills for a request; you choose |
/router workflows |
List defined multi-skill workflows |
/router run <workflow> |
Walk a named workflow step by step, with handoffs |
Cookbook
Each command has a detailed step-by-step guide. Read the relevant cookbook file before executing a command.
| Command | Cookbook | Use When |
|---|---|---|
| setup | cookbook/setup.md | First-time install, or the hook/DB is missing or broken |
| stats | cookbook/stats.md | User wants most-used / top skills or usage numbers |
| pick | cookbook/pick.md | User wants to choose a skill for a task, or "what should I use" |
| workflows | cookbook/workflows.md | User wants to list, run, or define a back-to-back workflow |
When a user invokes a /router command, read the matching cookbook file first, then execute the steps.
Reference
- references/schema.md — DB schema, hook mechanics, and the workflow file format.
Notes
- The hook records skills invoked through the
Skilltool in the main session, which includes skills you trigger with/slash(the agent routes those through theSkilltool). Counting starts whensetupruns — there is no backfill. - Plugin skills (e.g.
superpowers:brainstorming) are tracked by name even though theirSKILL.mdlives in the plugin cache rather than the scanned catalog roots; combine the file catalog with the live in-context skill list when picking.