@originkit/skillrouter 0.1.0 → 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 +23 -59
- package/data/keywords.json +6725 -0
- package/data/skills.json +2 -41
- package/dist/cli.js +25 -12
- package/dist/index.d.ts +9 -2
- package/dist/index.js +29 -11
- package/dist/mcp.js +15 -14
- package/dist/types.d.ts +9 -0
- package/docs/integrate.md +234 -0
- package/docs/setup.md +278 -0
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -6,73 +6,31 @@ You install one thing, the router, instead of every skill. It routes over each s
|
|
|
6
6
|
|
|
7
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
8
|
|
|
9
|
-
> Not on npm yet. The commands below use the planned name `@originkit/skillrouter`.
|
|
10
9
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
### Claude Code: plugin (recommended)
|
|
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.
|
|
14
11
|
|
|
15
|
-
|
|
16
|
-
/plugin install skill-router --marketplace landerdevelopers/skill-router
|
|
17
|
-
```
|
|
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.
|
|
18
13
|
|
|
19
|
-
|
|
14
|
+
## Install
|
|
20
15
|
|
|
21
|
-
|
|
16
|
+
**Full step-by-step for every tool: [docs/setup.md](docs/setup.md).** Quick start:
|
|
22
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**.
|
|
23
19
|
```sh
|
|
24
|
-
claude
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
### Claude Desktop: one-click extension
|
|
28
|
-
|
|
29
|
-
Download `skill-router.mcpb` (built with `npm run build:mcpb`). Double-click it, or drag it into Settings → Extensions. You can also pick a skills folder to route over (the default is `~/.claude/skills`). It bundles everything; Claude Desktop supplies Node.
|
|
30
|
-
|
|
31
|
-
### Claude Desktop (manual), Cursor, Windsurf, Gemini CLI and other `mcpServers` clients
|
|
32
|
-
|
|
33
|
-
Add this to the client's MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, `~/.gemini/settings.json`, …):
|
|
34
|
-
|
|
35
|
-
```json
|
|
36
|
-
{
|
|
37
|
-
"mcpServers": {
|
|
38
|
-
"skill-router": { "command": "npx", "args": ["-y", "@originkit/skillrouter", "mcp"] }
|
|
39
|
-
}
|
|
40
|
-
}
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
### VS Code (Copilot): `.vscode/mcp.json`
|
|
44
|
-
|
|
45
|
-
```json
|
|
46
|
-
{ "servers": { "skill-router": { "type": "stdio", "command": "npx", "args": ["-y", "@originkit/skillrouter", "mcp"] } } }
|
|
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)
|
|
47
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.
|
|
48
25
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
```toml
|
|
52
|
-
[mcp_servers.skill-router]
|
|
53
|
-
command = "npx"
|
|
54
|
-
args = ["-y", "@originkit/skillrouter", "mcp"]
|
|
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`, …):
|
|
55
27
|
```
|
|
56
|
-
|
|
57
|
-
To include your own skills, add `"--skills", "/path/to/skills"` to the args (you can repeat it). Add `"--no-pack"` to leave out the bundled pack.
|
|
58
|
-
|
|
59
|
-
**Make the agent use it.** MCP tools are only called when the model decides to. Outside the Claude Code plugin, add one line to `AGENTS.md`, `CLAUDE.md` or `.cursor/rules`:
|
|
60
|
-
|
|
61
|
-
```
|
|
62
|
-
Before starting a substantial task, call route_skill with the task; if a skill fits, load it with get_skill and follow it.
|
|
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.
|
|
63
29
|
```
|
|
64
30
|
|
|
65
|
-
### Agents that read SKILL.md and have a shell
|
|
66
|
-
|
|
67
|
-
```sh
|
|
68
|
-
npx skills add https://github.com/landerdevelopers/skill-router --skill skill-router
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
This installs one small router skill that calls the CLI.
|
|
72
|
-
|
|
73
31
|
## MCP tools
|
|
74
32
|
|
|
75
|
-
- `route_skill(task, limit?)`:
|
|
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.
|
|
76
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.
|
|
77
35
|
|
|
78
36
|
## CLI
|
|
@@ -98,7 +56,8 @@ import { createRouter, loadPack, loadSkillsDir, loadSkillBody } from "@originkit
|
|
|
98
56
|
const router = createRouter([...loadPack(), ...loadSkillsDir("./skills")]); // build once, reuse
|
|
99
57
|
|
|
100
58
|
const res = await router.route("make the hero feel less generic");
|
|
101
|
-
// { matches: [{ skill, score,
|
|
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)
|
|
102
61
|
|
|
103
62
|
await router.route("make the hero feel less generic", {
|
|
104
63
|
complete: (prompt) => yourModel(prompt), // optional rerank, any provider; returns the model's text
|
|
@@ -121,23 +80,28 @@ You can also build `Skill` objects yourself (`{ id, name, description, source? }
|
|
|
121
80
|
|
|
122
81
|
| Where | What happens without asking | What you have to do |
|
|
123
82
|
|---|---|---|
|
|
124
|
-
| Claude Code plugin | Every prompt is routed. A skill you named has its instructions loaded into the context.
|
|
125
|
-
| MCP clients (Desktop, Cursor,
|
|
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 |
|
|
126
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()` |
|
|
127
86
|
|
|
128
87
|
## How it routes
|
|
129
88
|
|
|
130
|
-
1. **Lexical (offline, free).** BM25+ ([MiniSearch](https://github.com/lucaong/minisearch)) over each skill's name, summary, description and
|
|
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.
|
|
131
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.
|
|
132
|
-
3. **Model rerank (optional).** Pass any `complete(prompt)` function and a model picks from the
|
|
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).
|
|
133
94
|
|
|
134
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.
|
|
135
96
|
|
|
136
97
|
## Develop
|
|
137
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
|
+
|
|
138
101
|
```sh
|
|
139
102
|
npm test # unit tests (fixtures in test/fixtures)
|
|
140
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)
|
|
141
105
|
npm run build
|
|
142
106
|
claude plugin validate .
|
|
143
107
|
```
|