Skip to content
Back to search

skill-router

MarketplaceWorks with Claude CodeGitHub

skill-router: Claude Code loads the right skills, all of them, and you can prove it.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/emoubarak--claude-skill-router/badge.svg)](/listings/emoubarak--claude-skill-router)

HTML

<a href="/listings/emoubarak--claude-skill-router"><img src="/api/listings/emoubarak--claude-skill-router/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

/plugin marketplace add emoubarak/claude-skill-router
/plugin install skill-router@skill-router

Then write your rules in `~/.config/skill-router/rules.json` (start from [examples/rules.example.json](examples/rules.example.json)); a repo can add its own in `.claude/skill-router.json`.

{
  "rules": [
    {"skill": "seo", "pattern": "\\bseo\\b|search console|semrush|backlinks?", "why": "SEO"},
    {"skill": "invoices", "pattern": "invoices?|receipts?", "cwd": "/accounting\\b", "why": "bookkeeping repo only"}
  ],
  "replaces": [{"if": "channel-video", "drop": "video"}],
  "always_available": ["recall"]
}

Modes (`SKILL_ROUTER_MODE`): `both` (default), `rules`, `reminder`, `off`.

Skills from plugins or built into Claude Code have no folder to check: list them in `always_available`, or their rules never fire. Project skills are suggested only inside their repo (the hook looks for `<parent>/.claude/skills/<name>`). A repo's `.claude/skill-router.json` can add rules but cannot change the injected text.

**Privacy.** The hook logs, per prompt, the suggested skills and the first 160 characters of the prompt to `~/.local/share/skill-router/log.jsonl`, for `review.py`. Nothing leaves your machine. `SKILL_ROUTER_LOG=""` turns it off.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 8 lines
  1. {
  2. "name": "skill-router",
  3. "owner": {"name": "El Mahdi Moubarak", "url": "https://github.com/emoubarak"},
  4. "plugins": [
  5. {"name": "skill-router", "source": "./", "description": "Make Claude Code load every skill that fits a prompt, measured on your own sessions."}
  6. ],
  7. "description": "skill-router: Claude Code loads the right skills, all of them, and you can prove it."
  8. }
README.md · README · 111 lines
  1. # skill-router
  2. **Claude Code loads the skills that fit a prompt, all of them, and you can measure it on your own sessions.**
  3. With a handful of skills, Claude picks the right one. With a hundred, it does not: on my own prompts, replayed
  4. against my real setup, Claude loaded only **57 %** of the skills a request needed, and every needed skill in only
  5. **half** of the requests. Descriptions alone are not enough. "Check the Search Console alerts for the agency site"
  6. loaded the browser skill and skipped the SEO skill, whose description contains that exact phrase.
  7. skill-router is a `UserPromptSubmit` hook plus the bench that proved it works:
  8. | Held-out prompts (77 needing skills, 40 needing none, 2 passes) | Without | With skill-router |
  9. |---|---|---|
  10. | Needed skills loaded (recall) | 57 % | **84 %** |
  11. | Requests where every needed skill loaded | 52 % | **82 %** |
  12. | Prompts needing no skill left clean | 99 % | 95 % |
  13. A third set drawn after the last fixes, never used for tuning, gave the same picture: recall 74 % to **93 %**, every
  14. needed skill in 59/80 to **74/80** requests (final version, after an independent code review). Replayed **in the
  15. middle of real sessions** (the transcript cut just before the prompt, then `--resume`), 28 prompts: recall 43 % to
  16. **80 %**, every needed skill in 8/23 to **18/23**. A fifth set, drawn after the last rule fix: 82 % to **94 %**, 42/50 to
  17. **47/50**, no change on prompts that need no skill (23/25 both).
  18. Measured with Claude Opus 5.5 in Claude Code 2.1.328, 80 to 95 skills per session depending on the repo (global,
  19. project and plugin), real prompts from 75 days of work. Labels were proposed by four labelling agents and reviewed in
  20. a second pass. Details and caveats: [bench/README.md](bench/README.md).
  21. ## How it works
  22. On each prompt the hook adds one or two lines to Claude's context:
  23. 1. **Rules in your words.** A regex per skill, written from how *you* ask for things ("the notifs of the search
  24. console", "make it a skill", "post it on X"), filtered by the current directory for project skills, each skill
  25. named once per session. Claude still decides: the line says "load these before acting, skip one only if it is
  26. clearly off topic".
  27. 2. **A reminder** that a request often needs several skills (content + video + ticket), so Claude does not stop at
  28. the first match.
  29. Each half alone gave the same gain on the dev set (66 % to 84 % recall), together 89 %, and 93 % once the injected
  30. line said "before any other action" instead of "each one that really applies". Fixing four descriptions took it to
  31. 96 %. The held-out numbers above are the honest ones.
  32. It costs about 150 tokens per prompt (median, measured) and about 20 ms. No model call, no server, no dependency.
  33. ## Install
  34. ```
  35. /plugin marketplace add emoubarak/claude-skill-router
  36. /plugin install skill-router@skill-router
  37. ```
  38. Then write your rules in `~/.config/skill-router/rules.json` (start from
  39. [examples/rules.example.json](examples/rules.example.json)); a repo can add its own in `.claude/skill-router.json`.
  40. ```json
  41. {
  42. "rules": [
  43. {"skill": "seo", "pattern": "\\bseo\\b|search console|semrush|backlinks?", "why": "SEO"},
  44. {"skill": "invoices", "pattern": "invoices?|receipts?", "cwd": "/accounting\\b", "why": "bookkeeping repo only"}
  45. ],
  46. "replaces": [{"if": "channel-video", "drop": "video"}],
  47. "always_available": ["recall"]
  48. }
  49. ```
  50. Modes (`SKILL_ROUTER_MODE`): `both` (default), `rules`, `reminder`, `off`.
  51. Skills from plugins or built into Claude Code have no folder to check: list them in `always_available`, or their
  52. rules never fire. Project skills are suggested only inside their repo (the hook looks for
  53. `<parent>/.claude/skills/<name>`). A repo's `.claude/skill-router.json` can add rules but cannot change the injected
  54. text.
  55. **Privacy.** The hook logs, per prompt, the suggested skills and the first 160 characters of the prompt to
  56. `~/.local/share/skill-router/log.jsonl`, for `review.py`. Nothing leaves your machine. `SKILL_ROUTER_LOG=""` turns it off.
  57. ## Write the rules from your history, not from your skills
  58. The useful words are the ones you type, not the ones in the descriptions. `bench/extract.py` pulls every prompt from
  59. your transcripts with the skills Claude loaded after it: read the misses and copy your phrasing into the patterns.
  60. `bench/offline.py gold.jsonl` scores the rules alone in a second.
  61. ## Measure it on your own setup
  62. `bench/bench.py` replays a labelled set of your prompts through `claude -p` against a **copy** of `~/.claude`
  63. (`CLAUDE_CONFIG_DIR`), in each prompt's original directory, with a guard hook that lets Claude choose skills and read
  64. files but denies every action. Your real config, usage counters and history are untouched. Change one thing per copy
  65. (a hook, a description, a `skillOverrides` entry) and compare. The method, and what I learned from about 1,600 replays, is in
  66. [bench/README.md](bench/README.md).
  67. ## Keep it honest
  68. Rules rot: you start a new project, you phrase things differently. `maintenance/review.py` reads the log the hook
  69. writes and your transcripts, and lists per skill: suggested then loaded, suggested and ignored (pattern too wide),
  70. loaded without a suggestion (words missing, with your prompt quoted), plus your own complaints ("you skipped the
  71. skill"). Run it weekly; with `--gold` it also re-scores the rules so an edit that hurts shows up.
  72. ## What did not help
  73. - **Hiding skills** (`skillOverrides: name-only` on 17 overlapping third-party skills): same recall, more noise on
  74. prompts that need no skill.
  75. - **Renaming skills**: names were already explicit; with the router you no longer need to remember them.
  76. - **The listing budget** was not the cause on my setup once raised (`skillListingBudgetFraction: 0.02`), but check
  77. yours: `claude --debug` logs "Skill listing over budget" when descriptions get dropped, and a dropped description
  78. is a skill Claude will almost never pick.
  79. Also found on the way: a `description:` spanning several lines with a `: ` inside is not valid YAML, and Claude Code
  80. silently falls back to the skill's title. Quote it or use `>-`.
  81. ## License
  82. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.