@originkit/skillrouter 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -2
- package/data/keywords.json +6725 -0
- package/data/skills.json +4167 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +123 -0
- package/dist/index.d.ts +62 -0
- package/dist/index.js +343 -0
- package/dist/mcp.d.ts +6 -0
- package/dist/mcp.js +56 -0
- package/dist/types.d.ts +50 -0
- package/dist/types.js +1 -0
- package/docs/integrate.md +234 -0
- package/docs/setup.md +278 -0
- package/package.json +51 -4
package/README.md
CHANGED
|
@@ -1,3 +1,107 @@
|
|
|
1
|
-
#
|
|
1
|
+
# skill-router
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Pick the right agent skill for a task, whether you have 2 skills or 200, or say honestly that none fits. Then load only that skill.
|
|
4
|
+
|
|
5
|
+
You install one thing, the router, instead of every skill. It routes over each skill's name and description (250 skills is about 180 KB and takes 0.1 ms per task). A skill's full instructions are fetched only when it gets picked, from a URL pinned to a commit, and cached.
|
|
6
|
+
|
|
7
|
+
It works with any skill in the open `SKILL.md` format, and with any harness: a Claude Code plugin, an MCP server (Claude Desktop, Cursor, VS Code, Codex, Windsurf, …), a CLI, or a TypeScript library. It ships with a pre-loaded pack of web-design skills (`data/skills.json`), and you can add your own folders.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
**Setting it up?** Follow **[docs/setup.md](docs/setup.md)**: step-by-step for Claude Code in VS Code (recommended), the terminal, Claude Desktop, Copilot, Cursor, Windsurf, Codex and Gemini CLI.
|
|
11
|
+
|
|
12
|
+
**Adding it to your own app or agent?** Follow [docs/integrate.md](docs/integrate.md): step by step, with checks, written so you can hand it to a coding agent.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
**Full step-by-step for every tool: [docs/setup.md](docs/setup.md).** Quick start:
|
|
17
|
+
|
|
18
|
+
**Claude Code** (terminal or VS Code). In VS Code you can instead type `/plugins` in the Claude panel, add the marketplace `landerdevelopers/skill-router`, and install **skill-router**.
|
|
19
|
+
```sh
|
|
20
|
+
claude plugin marketplace add landerdevelopers/skill-router
|
|
21
|
+
claude plugin install skill-router@skill-router
|
|
22
|
+
npm i -g @originkit/skillrouter # optional: faster hook (under 0.1 s per prompt instead of ~0.3 s via npx)
|
|
23
|
+
```
|
|
24
|
+
Every prompt is then routed automatically. When skills fit, Claude gets up to 8 one-line candidates (~300 tokens), picks the best fit, and loads it before it starts. A skill you name (`/break-ui`, "use the seo skill") is loaded straight away.
|
|
25
|
+
|
|
26
|
+
**Any MCP client** (Claude Desktop, Cursor, Copilot, Windsurf, Codex, Gemini CLI, …): `npx -y @originkit/skillrouter mcp` over stdio. Then add this line to the tool's instructions file (`AGENTS.md`, `.cursor/rules`, …):
|
|
27
|
+
```
|
|
28
|
+
Before design, copy, SEO, accessibility, performance or motion work, call route_skill with the task. Pick the skill that best fits (not necessarily the first), load it with get_skill and follow it. If none fits, carry on without one.
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## MCP tools
|
|
32
|
+
|
|
33
|
+
- `route_skill(task, limit?)`: up to 40 candidate skills, one line each, with cautions. The agent's own model picks from them, so the server needs no API key.
|
|
34
|
+
- `get_skill(id, file?)`: the skill's `SKILL.md`, or a file it references (`references/rules.md`). It is fetched once, then cached in `~/.cache/skill-router`. This lets harnesses with no native skill support use skills too.
|
|
35
|
+
|
|
36
|
+
## CLI
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
skill-router route "our landing page doesn't convert"
|
|
40
|
+
skill-router route --skills ~/.claude/skills --no-pack "dark mode palette"
|
|
41
|
+
skill-router list
|
|
42
|
+
skill-router show anthropics/skills/frontend-design
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Options:
|
|
46
|
+
- `--skills <dir>` adds a folder of `SKILL.md` skills (repeatable).
|
|
47
|
+
- `--no-pack` leaves out the bundled pack.
|
|
48
|
+
- `-k` sets the maximum number of results.
|
|
49
|
+
- `--json` gives machine-readable output.
|
|
50
|
+
|
|
51
|
+
## Library
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { createRouter, loadPack, loadSkillsDir, loadSkillBody } from "@originkit/skillrouter";
|
|
55
|
+
|
|
56
|
+
const router = createRouter([...loadPack(), ...loadSkillsDir("./skills")]); // build once, reuse
|
|
57
|
+
|
|
58
|
+
const res = await router.route("make the hero feel less generic");
|
|
59
|
+
// { matches: [{ skill, score, mentioned? }], none: false, via: "lexical", confidence: 0.91 }
|
|
60
|
+
// confidence 0..1: how much of the task the top skill covers (1 when the task names a skill)
|
|
61
|
+
|
|
62
|
+
await router.route("make the hero feel less generic", {
|
|
63
|
+
complete: (prompt) => yourModel(prompt), // optional rerank, any provider; returns the model's text
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
const instructions = await loadSkillBody(res.matches[0].skill, { cacheDir: "/app/data/skills" });
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
You can also build `Skill` objects yourself (`{ id, name, description, source? }`) from a database or an API. Nothing requires files.
|
|
70
|
+
|
|
71
|
+
## Which skills it knows, and when it acts
|
|
72
|
+
|
|
73
|
+
**Skills you already have** are found automatically in `~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, `~/.cursor/skills` and the same folders inside the project (`--no-discover` turns this off, and `--skills <dir>` adds more). If one is also in the catalog, it shows up once, under the catalog id, using your installed copy. Installed skills rank slightly higher, because you chose them.
|
|
74
|
+
|
|
75
|
+
**New installs** are seen right away. The hook and every MCP call re-read the folders, which costs about 17 ms, so there's no restart.
|
|
76
|
+
|
|
77
|
+
**Naming a skill** puts it first, whatever the scores say. You can write `/frontend-design`, `$seo-audit`, `run break-ui on…`, `use the seo skill`, or a full id. A single-word name needs "skill" after it, so "animate the cards" doesn't count as naming `animate`. When several skills share a name, one whose owner you mention wins ("emilkowalski's animate skill"), then an installed one, then the best match.
|
|
78
|
+
|
|
79
|
+
**Automatic or explicit?**
|
|
80
|
+
|
|
81
|
+
| Where | What happens without asking | What you have to do |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| Claude Code plugin | Every prompt is routed. A skill you named has its instructions loaded into the context. Otherwise Claude gets up to 8 candidates and loads the best fit before starting, or none if nothing is about the task | Nothing |
|
|
84
|
+
| MCP clients (Desktop, Cursor, Copilot, Codex, …) | Nothing runs on its own: the model calls `route_skill` when it judges a task needs a skill. The server's instructions and tool description push it to | For reliability, add the one-line rule (above) to the tool's instructions file |
|
|
85
|
+
| Your app (library) | Whatever you wire: e.g. route every message on the server and attach the instructions before the model runs | Call `router.route()` |
|
|
86
|
+
|
|
87
|
+
## How it routes
|
|
88
|
+
|
|
89
|
+
1. **Lexical (offline, free).** BM25+ ([MiniSearch](https://github.com/lucaong/minisearch)) over each skill's name, summary, description, categories and **problem keywords**: the words people type when they need the skill ("cramped", "janky hover", "nobody clicks"), generated once per skill (`data/keywords.json`). Names are boosted, "main pick" skills get a small nudge, and "use with care" skills a small penalty.
|
|
90
|
+
2. **No-fit check.** If the top hit scores too low, or matches too few of the task's meaningful words, the answer is *no skill*. A wrong skill is worse than none.
|
|
91
|
+
3. **Model rerank (optional).** Pass any `complete(prompt)` function and a model picks from the top 40, giving a confidence and a reason, or none. Over MCP and in the Claude Code plugin, the calling agent does this step itself.
|
|
92
|
+
|
|
93
|
+
**How well it works.** On 101 blind prompts, the right skill is in the top 40 for 98% of tasks, and a small model picking from that list gets it right first 73% of the time. In real Claude Code sessions, the router loaded a genuinely useful skill for 77% of tasks, against 39% with all ~250 skills installed natively. It was also faster per prompt (8.1 s vs 8.4 s median) and cheaper ($0.042 vs $0.068). Details and caveats: [bench/README.md](bench/README.md).
|
|
94
|
+
|
|
95
|
+
Skills are keyed by `owner/repo/skill`, because names collide: `animate` and `seo` each exist in several repos. Duplicate copies of the same skill count once. `SKILL.md` frontmatter that isn't strictly valid YAML (`description: Triggers on: …`) still loads, as harnesses accept it.
|
|
96
|
+
|
|
97
|
+
## Develop
|
|
98
|
+
|
|
99
|
+
Inside this repo, `npx @originkit/skillrouter` resolves to the repo itself, not npm, and fails with `skill-router: command not found`. Run the source directly with `node src/cli.ts route "…"`, or `npm link` once to put your working copy on PATH as `skill-router`.
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
npm test # unit tests (fixtures in test/fixtures)
|
|
103
|
+
npm run eval # routing quality on data/eval.json; add -- --sweep to calibrate thresholds
|
|
104
|
+
npm run eval -- --file data/eval-holdout.json --rerank # blind set; --rerank also scores a small-model pick (uses claude -p)
|
|
105
|
+
npm run build
|
|
106
|
+
claude plugin validate .
|
|
107
|
+
```
|