@originkit/skillrouter 0.0.0-stage → 0.1.0
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 +142 -2
- package/data/skills.json +4206 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +110 -0
- package/dist/index.d.ts +55 -0
- package/dist/index.js +325 -0
- package/dist/mcp.d.ts +6 -0
- package/dist/mcp.js +55 -0
- package/dist/types.d.ts +41 -0
- package/dist/types.js +1 -0
- package/package.json +48 -4
package/README.md
CHANGED
|
@@ -1,3 +1,143 @@
|
|
|
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
|
+
> Not on npm yet. The commands below use the planned name `@originkit/skillrouter`.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
### Claude Code: plugin (recommended)
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
/plugin install skill-router --marketplace landerdevelopers/skill-router
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
On every prompt, a hook routes your message (about 50–100 ms) and adds the skills that fit, if any, to the context. If you named a skill, its instructions are loaded straight away. The model doesn't have to remember to ask. The plugin also adds the MCP tools below.
|
|
20
|
+
|
|
21
|
+
### Claude Code: MCP only
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
claude mcp add skill-router -- npx -y @originkit/skillrouter mcp
|
|
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"] } } }
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Codex: `~/.codex/config.toml`
|
|
50
|
+
|
|
51
|
+
```toml
|
|
52
|
+
[mcp_servers.skill-router]
|
|
53
|
+
command = "npx"
|
|
54
|
+
args = ["-y", "@originkit/skillrouter", "mcp"]
|
|
55
|
+
```
|
|
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.
|
|
63
|
+
```
|
|
64
|
+
|
|
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
|
+
## MCP tools
|
|
74
|
+
|
|
75
|
+
- `route_skill(task, limit?)`: a ranked shortlist with descriptions and cautions. The agent's own model picks from it, so the server needs no API key.
|
|
76
|
+
- `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
|
+
|
|
78
|
+
## CLI
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
skill-router route "our landing page doesn't convert"
|
|
82
|
+
skill-router route --skills ~/.claude/skills --no-pack "dark mode palette"
|
|
83
|
+
skill-router list
|
|
84
|
+
skill-router show anthropics/skills/frontend-design
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Options:
|
|
88
|
+
- `--skills <dir>` adds a folder of `SKILL.md` skills (repeatable).
|
|
89
|
+
- `--no-pack` leaves out the bundled pack.
|
|
90
|
+
- `-k` sets the maximum number of results.
|
|
91
|
+
- `--json` gives machine-readable output.
|
|
92
|
+
|
|
93
|
+
## Library
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
import { createRouter, loadPack, loadSkillsDir, loadSkillBody } from "@originkit/skillrouter";
|
|
97
|
+
|
|
98
|
+
const router = createRouter([...loadPack(), ...loadSkillsDir("./skills")]); // build once, reuse
|
|
99
|
+
|
|
100
|
+
const res = await router.route("make the hero feel less generic");
|
|
101
|
+
// { matches: [{ skill, score, reason? }], none: false, via: "lexical" }
|
|
102
|
+
|
|
103
|
+
await router.route("make the hero feel less generic", {
|
|
104
|
+
complete: (prompt) => yourModel(prompt), // optional rerank, any provider; returns the model's text
|
|
105
|
+
});
|
|
106
|
+
|
|
107
|
+
const instructions = await loadSkillBody(res.matches[0].skill, { cacheDir: "/app/data/skills" });
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
You can also build `Skill` objects yourself (`{ id, name, description, source? }`) from a database or an API. Nothing requires files.
|
|
111
|
+
|
|
112
|
+
## Which skills it knows, and when it acts
|
|
113
|
+
|
|
114
|
+
**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.
|
|
115
|
+
|
|
116
|
+
**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.
|
|
117
|
+
|
|
118
|
+
**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.
|
|
119
|
+
|
|
120
|
+
**Automatic or explicit?**
|
|
121
|
+
|
|
122
|
+
| Where | What happens without asking | What you have to do |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| Claude Code plugin | Every prompt is routed. A skill you named has its instructions loaded into the context. Other matches are suggested, and the model uses one only if it fits | Nothing |
|
|
125
|
+
| MCP clients (Desktop, Cursor, VS Code, 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 to `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` (above) |
|
|
126
|
+
| 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
|
+
|
|
128
|
+
## How it routes
|
|
129
|
+
|
|
130
|
+
1. **Lexical (offline, free).** BM25+ ([MiniSearch](https://github.com/lucaong/minisearch)) over each skill's name, summary, description and categories. Names are boosted, "main pick" skills get a small nudge, and "use with care" skills a small penalty.
|
|
131
|
+
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 shortlist, giving a confidence and a reason, or none. Over MCP, the calling agent does this step itself.
|
|
133
|
+
|
|
134
|
+
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
|
+
|
|
136
|
+
## Develop
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
npm test # unit tests (fixtures in test/fixtures)
|
|
140
|
+
npm run eval # routing quality on data/eval.json; add -- --sweep to calibrate thresholds
|
|
141
|
+
npm run build
|
|
142
|
+
claude plugin validate .
|
|
143
|
+
```
|