@originkit/skillrouter 0.1.0 → 0.1.2
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/.claude-plugin/marketplace.json +16 -0
- package/README.md +24 -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 +282 -0
- package/package.json +8 -2
- package/plugin/.claude-plugin/plugin.json +39 -0
- package/skills/skill-router/SKILL.md +24 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "skill-router",
|
|
3
|
+
"owner": {
|
|
4
|
+
"name": "landerdevelopers"
|
|
5
|
+
},
|
|
6
|
+
"metadata": {
|
|
7
|
+
"description": "Skill routing for Claude Code: the right skill per prompt, loaded on demand."
|
|
8
|
+
},
|
|
9
|
+
"plugins": [
|
|
10
|
+
{
|
|
11
|
+
"name": "skill-router",
|
|
12
|
+
"source": "./plugin",
|
|
13
|
+
"description": "Picks the right skill for each prompt and loads only that one."
|
|
14
|
+
}
|
|
15
|
+
]
|
|
16
|
+
}
|
package/README.md
CHANGED
|
@@ -6,73 +6,32 @@ 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 **[the setup guide](https://unpkg.com/@originkit/skillrouter/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 [the integration guide](https://unpkg.com/@originkit/skillrouter/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: [setup guide](https://unpkg.com/@originkit/skillrouter/docs/setup.md).** Quick start:
|
|
22
17
|
|
|
18
|
+
**Claude Code** (terminal or VS Code). The plugin ships inside the npm package:
|
|
23
19
|
```sh
|
|
24
|
-
|
|
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
|
+
npm i -g @originkit/skillrouter
|
|
21
|
+
claude plugin marketplace add "$(npm root -g)/@originkit/skillrouter"
|
|
22
|
+
claude plugin install skill-router@skill-router
|
|
47
23
|
```
|
|
24
|
+
In VS Code you can instead type `/plugins` in the Claude panel, add that folder as a marketplace, and install **skill-router**.
|
|
25
|
+
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
26
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
```toml
|
|
52
|
-
[mcp_servers.skill-router]
|
|
53
|
-
command = "npx"
|
|
54
|
-
args = ["-y", "@originkit/skillrouter", "mcp"]
|
|
27
|
+
**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
28
|
```
|
|
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.
|
|
29
|
+
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
30
|
```
|
|
64
31
|
|
|
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
32
|
## MCP tools
|
|
74
33
|
|
|
75
|
-
- `route_skill(task, limit?)`:
|
|
34
|
+
- `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
35
|
- `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
36
|
|
|
78
37
|
## CLI
|
|
@@ -98,7 +57,8 @@ import { createRouter, loadPack, loadSkillsDir, loadSkillBody } from "@originkit
|
|
|
98
57
|
const router = createRouter([...loadPack(), ...loadSkillsDir("./skills")]); // build once, reuse
|
|
99
58
|
|
|
100
59
|
const res = await router.route("make the hero feel less generic");
|
|
101
|
-
// { matches: [{ skill, score,
|
|
60
|
+
// { matches: [{ skill, score, mentioned? }], none: false, via: "lexical", confidence: 0.91 }
|
|
61
|
+
// confidence 0..1: how much of the task the top skill covers (1 when the task names a skill)
|
|
102
62
|
|
|
103
63
|
await router.route("make the hero feel less generic", {
|
|
104
64
|
complete: (prompt) => yourModel(prompt), // optional rerank, any provider; returns the model's text
|
|
@@ -121,23 +81,28 @@ You can also build `Skill` objects yourself (`{ id, name, description, source? }
|
|
|
121
81
|
|
|
122
82
|
| Where | What happens without asking | What you have to do |
|
|
123
83
|
|---|---|---|
|
|
124
|
-
| Claude Code plugin | Every prompt is routed. A skill you named has its instructions loaded into the context.
|
|
125
|
-
| MCP clients (Desktop, Cursor,
|
|
84
|
+
| 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 |
|
|
85
|
+
| 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
86
|
| 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
87
|
|
|
128
88
|
## How it routes
|
|
129
89
|
|
|
130
|
-
1. **Lexical (offline, free).** BM25+ ([MiniSearch](https://github.com/lucaong/minisearch)) over each skill's name, summary, description and
|
|
90
|
+
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
91
|
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
|
|
92
|
+
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.
|
|
93
|
+
|
|
94
|
+
**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 are in the repo's `bench/README.md`.
|
|
133
95
|
|
|
134
96
|
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
97
|
|
|
136
98
|
## Develop
|
|
137
99
|
|
|
100
|
+
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`.
|
|
101
|
+
|
|
138
102
|
```sh
|
|
139
103
|
npm test # unit tests (fixtures in test/fixtures)
|
|
140
104
|
npm run eval # routing quality on data/eval.json; add -- --sweep to calibrate thresholds
|
|
105
|
+
npm run eval -- --file data/eval-holdout.json --rerank # blind set; --rerank also scores a small-model pick (uses claude -p)
|
|
141
106
|
npm run build
|
|
142
107
|
claude plugin validate .
|
|
143
108
|
```
|