@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 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
- ## Install
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
- 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.
14
+ ## Install
20
15
 
21
- ### Claude Code: MCP only
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 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"] } } }
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
- ### Codex: `~/.codex/config.toml`
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?)`: a ranked shortlist with descriptions and cautions. The agent's own model picks from it, so the server needs no API key.
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, reason? }], none: false, via: "lexical" }
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. 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) |
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 categories. Names are boosted, "main pick" skills get a small nudge, and "use with care" skills a small penalty.
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 shortlist, giving a confidence and a reason, or none. Over MCP, the calling agent does this step itself.
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
  ```