@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.
@@ -0,0 +1,234 @@
1
+ # Integrating skill-router into an app or agent
2
+
3
+ This guide is written so that a person, or a coding agent (Claude Code, Cursor, Codex, …) handed this file, can add skill routing to an app that runs an AI agent. Follow it top to bottom. Every step ends with a check.
4
+
5
+ > **Agents:** do the steps in order and run each check before moving on. Don't skip the bundling step (step 5) if the app bundles its server.
6
+
7
+ ## What you're adding
8
+
9
+ Your agent gets the right skill, meaning expert instructions in a `SKILL.md`, for the task at hand. You don't install every skill or paste them all into the prompt. The router keeps a small index of skill names, descriptions and problem keywords. It ships with 256 web-design skills, and you can add your own. For each task, it does three things:
10
+
11
+ 1. **Shortlists** candidates with offline word matching (BM25 plus problem keywords). Building the index takes about 11 ms at startup, and each query takes about 0.1 ms.
12
+ 2. **Lets a model pick** from the shortlist: either your agent itself, or a cheap model you plug in.
13
+ 3. **Loads only the picked skill's instructions**, fetched once from a commit-pinned URL and cached.
14
+
15
+ **Step 2 is not optional for quality.** On a blind test of 101 realistic prompts:
16
+
17
+ | | Word matching alone | Model picks from top 40 |
18
+ |---|---|---|
19
+ | Right skill first | 48% | **73%** |
20
+ | Symptom prompts ("people bounce in 3 s") | 33% | **76%** |
21
+ | Off-topic correctly rejected | 5/20 | **19/20** |
22
+ | Right skill somewhere in the top 40 | 98% | — |
23
+
24
+ Word matching is good at getting the right skill *into* the list, and a model is good at picking it *out*. Design your integration so a model makes the final pick from a wide list.
25
+
26
+ ## Step 1: Install
27
+
28
+ ```sh
29
+ npm i @originkit/skillrouter # Node ≥ 22, ESM (CommonJS require() also works)
30
+ ```
31
+
32
+ Use version **0.1.1 or later**: it has the problem keywords, `confidence`, and the 40-candidate default.
33
+
34
+ ✅ Check: `node -e 'import("@originkit/skillrouter").then(m => console.log(Object.keys(m)))'` lists `createRouter`, `loadPack` and `loadSkillBody`.
35
+
36
+ ## Step 2: Build one router at startup
37
+
38
+ ```ts
39
+ import { createRouter, loadPack, loadSkillsDir, loadSkillBody } from "@originkit/skillrouter";
40
+
41
+ // Once per process, not per request.
42
+ export const router = createRouter([
43
+ ...loadPack(), // the bundled 256 web-design skills (+ their keywords)
44
+ // ...loadSkillsDir("./skills"), // optional: your own SKILL.md folders
45
+ // ...skillsFromDb, // optional: { id, name, description, source?, keywords? }[]
46
+ ]);
47
+ ```
48
+
49
+ Choose which skills the router knows:
50
+ - **Server or multi-user app:** the catalog plus your own skills only. **Don't** call `discoverSkills()`, which reads `~/.claude/skills` and similar folders on the machine it runs on. That's right for a personal CLI tool and wrong for a server, because every user would see whatever happens to be installed on the host.
51
+ - **Your own catalog instead of the pack:** pass `Skill` objects. `id` must be unique; use `owner/repo/skill`, because names collide (`seo` exists in 4 repos). Add `source` (a raw `SKILL.md` URL **pinned to a commit**) so `loadSkillBody` can fetch it. Add `keywords` (the words users type when they need the skill: "cramped", "janky", "nobody clicks") for much better recall.
52
+
53
+ ✅ Check: `(await router.route("our pricing page buttons feel flat", { k: 40, relative: 0 })).matches.some(m => m.skill.name === "make-interfaces-feel-better")` is `true`.
54
+
55
+ ## Step 3: Choose an integration pattern
56
+
57
+ | Your app… | Use |
58
+ |---|---|
59
+ | runs an agent with tools (Claude Agent SDK, Vercel AI SDK, OpenAI tools, LangChain, MCP) | **Pattern A: two tools.** The agent picks. Recommended. |
60
+ | builds one prompt per request with no tool calls | **Pattern B: route before the call.** A cheap model picks, and you inject the instructions. |
61
+ | is a user's own coding agent (Claude Code, Cursor, Desktop, Codex) | Not this guide: use the plugin or MCP server ([README](../README.md#install)). |
62
+
63
+ ### Pattern A: two tools, the agent picks (recommended)
64
+
65
+ Give the agent a **wide, cheap list** (40 one-line candidates, about 1.3k tokens) and a way to load one. Don't pre-filter to 3: the right skill often isn't first by word matching, because tasks name their page ("pricing page") as loudly as their problem ("buttons feel flat").
66
+
67
+ The tool logic is shared by every framework:
68
+
69
+ ```ts
70
+ import type { Skill } from "@originkit/skillrouter";
71
+
72
+ const CACHE_DIR = "/var/cache/my-app/skills"; // writable; on serverless use os.tmpdir() or omit (memory only)
73
+
74
+ export async function findSkill(task: string): Promise<string> {
75
+ const res = await router.route(task, { k: 40, relative: 0 });
76
+ if (res.none) return "No skill fits this task. Go ahead without one.";
77
+ const lines = res.matches.map(({ skill: s, mentioned }, i) => {
78
+ const tags = [
79
+ mentioned ? "named in the task" : i === 0 && res.confidence >= 0.5 ? "strong match" : "",
80
+ s.warnings?.length ? `caution: ${s.warnings.join("; ")}` : "",
81
+ ].filter(Boolean);
82
+ const about = (s.summary ?? s.description).replace(/\s+/g, " ").slice(0, 200);
83
+ return `- ${s.id}: ${about}${tags.length ? ` [${tags.join(", ")}]` : ""}`;
84
+ });
85
+ return `${lines.join("\n")}\n\nRead the whole list and judge: word matching ranks the page a task mentions as highly as its problem, so the best skill may be far down. Load a pick with use_skill.`;
86
+ }
87
+
88
+ export async function useSkill(id: string, file?: string): Promise<string> {
89
+ const skill = router.get(id);
90
+ if (!skill) return `Unknown skill id: ${id}`;
91
+ // file: a reference the instructions point to, e.g. "references/rules.md". Paths outside the skill are refused.
92
+ const body = await loadSkillBody(skill, { file, cacheDir: CACHE_DIR }).catch((e: Error) => `Error: ${e.message}`);
93
+ return body ?? `${id} has no ${file ?? "instructions"} available.`;
94
+ }
95
+ ```
96
+
97
+ Then register them in your framework.
98
+
99
+ **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`):
100
+ ```ts
101
+ import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
102
+ import { z } from "zod";
103
+
104
+ const text = (t: string) => ({ content: [{ type: "text" as const, text: t }] });
105
+ export const skillTools = createSdkMcpServer({
106
+ name: "skills",
107
+ alwaysLoad: true, // no ToolSearch turn before the first use
108
+ version: "1.0.0",
109
+ tools: [
110
+ tool("find_skill", "Find expert skills for the current task. Returns ~40 candidates, one line each.", { task: z.string() },
111
+ async ({ task }) => text(await findSkill(task)), { annotations: { readOnlyHint: true } }),
112
+ tool("use_skill", "Load a skill's instructions (SKILL.md) or a file they reference.", { id: z.string(), file: z.string().optional() },
113
+ async ({ id, file }) => text(await useSkill(id, file)), { annotations: { readOnlyHint: true } }),
114
+ ],
115
+ });
116
+ // query({ prompt, options: { mcpServers: { skills: skillTools }, ... } })
117
+ ```
118
+
119
+ **Vercel AI SDK** (`ai` v5+):
120
+ ```ts
121
+ import { tool, stepCountIs, generateText } from "ai";
122
+ import { z } from "zod";
123
+
124
+ const tools = {
125
+ find_skill: tool({ description: "Find expert skills for the current task (~40 candidates, one line each).",
126
+ inputSchema: z.object({ task: z.string() }), execute: async ({ task }) => findSkill(task) }),
127
+ use_skill: tool({ description: "Load a skill's instructions (SKILL.md) or a file they reference.",
128
+ inputSchema: z.object({ id: z.string(), file: z.string().optional() }), execute: async ({ id, file }) => useSkill(id, file) }),
129
+ };
130
+ // generateText({ model, system, prompt, tools, stopWhen: stepCountIs(10) })
131
+ ```
132
+
133
+ **Any function-calling API** (OpenAI, Anthropic Messages, Gemini, …): declare `find_skill { task: string }` and `use_skill { id: string, file?: string }` as JSON-schema tools, and call `findSkill` / `useSkill` when the model invokes them.
134
+
135
+ **System prompt:** add this line, or the agent will rarely call the tools:
136
+ ```
137
+ Before design, copy, SEO, accessibility, performance or motion work, call find_skill with the task. If a skill fits, load it with use_skill and follow it; if none fits, go ahead without one.
138
+ ```
139
+ Adapt the list of work types to your catalog.
140
+
141
+ ✅ Check: ask your agent "our pricing page buttons feel flat". Its trace should show `find_skill`, then `use_skill("jakubkrehel/make-interfaces-feel-better/make-interfaces-feel-better")`, then work that follows those instructions. Ask "write a bash one-liner to rename .jpeg files": it should either not call `find_skill` or get "No skill fits".
142
+
143
+ ### Pattern B: route before the call, a cheap model picks
144
+
145
+ Use this when there's no tool loop. A small model picks from the top 40, which is the rerank measured above. It returns JSON naming its picks and the confidence, or none.
146
+
147
+ ```ts
148
+ const complete = async (prompt: string) => (await generateText({ model: "anthropic/claude-haiku-5-5", prompt })).text;
149
+ // or any provider: (prompt) => Promise<string> returning the model's text
150
+
151
+ const res = await router.route(userMessage, { complete, k: 2 }); // candidates defaults to 40
152
+ let system = baseSystemPrompt;
153
+ for (const { skill, score } of res.matches) {
154
+ if (score < 0.5) continue; // model's confidence
155
+ const body = await loadSkillBody(skill, { cacheDir: CACHE_DIR });
156
+ if (body) system += `\n\n<skill id="${skill.id}">\n${body}\n</skill>`;
157
+ }
158
+ ```
159
+
160
+ A rerank costs one small-model call of about 6k input tokens per message. To skip it for messages that obviously need no skill, check `router.route(msg)` first without `complete`, and rerank only when `!res.none`.
161
+
162
+ ✅ Check: the three prompts from Pattern A. The flat-buttons prompt injects `make-interfaces-feel-better`, and the bash prompt injects nothing.
163
+
164
+ ## Speed: what routing costs per generation
165
+
166
+ Routing itself takes about 0.1 ms. The time goes into **model turns** and **longer, skill-guided output**. These were measured in Claude Code with Sonnet, using the same tasks with and without the router:
167
+
168
+ | Task | No skills | With router |
169
+ |---|---|---|
170
+ | "our pricing page buttons feel flat, fix it" | 12.6 s | 13.4–14.5 s (loads `make-interfaces-feel-better`) |
171
+ | "add JSON-LD for our product" | 7.6 s | 11.7 s (loads `schema`) |
172
+ | "people leave within seconds, just tell me why" | 14.5 s | 14.0–16.3 s (answers directly, no skill) |
173
+
174
+ To keep a generation fast:
175
+ - **Put the shortlist in the prompt instead of a `find_skill` turn.** Route the user's message on your server before the model call (`router.route(msg, { k: 8, relative: 0, minCoverage: 0.1 })`), and when `!res.none && res.confidence >= 0.15`, add the 8 one-line candidates (~300 tokens) to that run's system prompt: "these skills match this request (already routed, so find_skill isn't needed); pick the best fit, not necessarily the first, load it with use_skill and follow it; skip only if none is about this task." Each tool turn you avoid saves roughly 4–5 s with Sonnet. Keep `find_skill` available for later turns. Why 8 lines and a low threshold: on the blind test that lists the right skill for 89% of real tasks (5 lines at 0.25 listed 77%), and in real Claude Code sessions a list that didn't fit was ignored every time (0 wrong loads on 9 off-topic prompts).
176
+ - **Keep the skill tools loaded up front.** Claude Code and the Agent SDK can defer tools until a `ToolSearch` step, which costs a turn. Mark them always-loaded: `createSdkMcpServer({ …, alwaysLoad: true })` with the Agent SDK, or `_meta: { "anthropic/alwaysLoad": true }` on each tool of a stdio MCP server (skill-router's own MCP server does this).
177
+ - **Pre-warm the cache at startup**, in the background, so `use_skill` never waits on the network (about 0.5 s per first fetch): `for (const s of router.skills) loadSkillBody(s, { cacheDir }).catch(() => {})`.
178
+ - **Route once per task, not per chat message.** "Thanks" or "make it bigger" shouldn't re-route; the router answers "no fit" for chit-chat anyway.
179
+ - **Pattern B's rerank** adds one small-model call before the main one. Through `claude -p` it measured about 3–4 s including process start; a direct API call to a small model is usually faster. Use it when accuracy matters more than a few seconds, or run it in parallel with other setup.
180
+ - **Skills make answers more thorough**, which means more output tokens. That's the quality you're buying. If a step must be minimal, say so in that step's prompt.
181
+
182
+ ## Step 4: Handle what the skill says
183
+
184
+ - **Instructions are text, not code.** Never execute scripts a skill mentions unless your agent already has a sandboxed shell and the user approves. `loadSkillBody` only returns text.
185
+ - **Show cautions.** Skills with `warnings` (audit warnings, "moved upstream") come back tagged `caution:`. The system-prompt line plus the tag is usually enough; for stricter apps, filter `s.warnings?.length` out of `findSkill`.
186
+ - **Treat skill text as instructions from a third party.** Only route over catalogs you trust. The bundled pack lists skills that pass, or are flagged by, three security audits, pinned to reviewed commits.
187
+
188
+ ## Step 5: Bundling and deploying
189
+
190
+ The pack's data files are resolved relative to the library's own `dist/` folder:
191
+ `node_modules/@originkit/skillrouter/data/skills.json` and `…/data/keywords.json`.
192
+
193
+ - **Plain Node with `node_modules` deployed:** nothing to do.
194
+ - **Bundled server (esbuild, Rollup, webpack, `ncc`):** the relative path breaks. Copy both files next to your bundle at build time and pass the path:
195
+ ```js
196
+ // build script (example: esbuild)
197
+ await copyFile("node_modules/@originkit/skillrouter/data/skills.json", "dist/skills.json");
198
+ await copyFile("node_modules/@originkit/skillrouter/data/keywords.json", "dist/keywords.json");
199
+ ```
200
+ ```ts
201
+ // at runtime: loadPack reads keywords.json from the same folder as skills.json
202
+ import { fileURLToPath } from "node:url";
203
+ loadPack(fileURLToPath(new URL("./skills.json", import.meta.url)));
204
+ ```
205
+ If you skip `keywords.json`, routing still works but loses most of its recall on symptom-style prompts.
206
+ - **Serverless (Vercel, Lambda):** make sure the two JSON files are traced or included in the function bundle (Next.js: `outputFileTracingIncludes`). Use `os.tmpdir()` or no `cacheDir`, since the filesystem is read-only.
207
+ - **Network:** `use_skill` fetches from `raw.githubusercontent.com` the first time a skill is used. Allow it, or pre-warm the cache at build time by calling `loadSkillBody` for the skills you expect.
208
+
209
+ ✅ Check: in the built and deployed artifact, run `router.skills.length` (it should be 255 plus your own: 256 catalog entries, one renamed skill folded into its successor) and `router.skills.some(s => s.keywords?.length)` (it should be `true`).
210
+
211
+ ## Step 6: Test it
212
+
213
+ Add these as tests in your app's own framework:
214
+
215
+ | Input | Expect |
216
+ |---|---|
217
+ | `findSkill("our pricing page buttons feel flat")` | contains `make-interfaces-feel-better` |
218
+ | `findSkill("people bounce from our homepage in 3 seconds")` | contains `page-cro` (gone upstream, so tagged with a caution) or `cro-methodology` |
219
+ | `findSkill("run break-ui on the dashboard")` | first line is `emilkowalski/skills/break-ui` `[named in the task]` |
220
+ | `findSkill("fix my postgres migration")` | `No skill fits` |
221
+ | `useSkill(id, "../../etc/passwd")` | an error, never file contents |
222
+ | `useSkill("nope/nope")` | `Unknown skill id` |
223
+
224
+ ## Reference
225
+
226
+ - `router.route(task, { k, relative, minCoverage, complete, candidates })` → `{ matches: [{ skill, score, mentioned?, reason? }], none, via, confidence }`
227
+ - `confidence` is 0–1: how much of the task the top skill covers, or the model's confidence after a rerank. It's 1 when the task names a skill (`/break-ui`, "the seo skill", a full id).
228
+ - Defaults: `k` 3, `relative` 0.5, `candidates` 40.
229
+ - `router.search(task, limit)`: raw word-matching ranking, unfiltered.
230
+ - `router.get(id)`: also resolves old ids of renamed skills.
231
+ - `loadSkillBody(skill, { file?, cacheDir?, fetch? })`: reads the local `path`, or fetches `source` once and caches it.
232
+ - `createRouter(skills, { keywordBoost })`: default keyword weight 2.
233
+
234
+ A worked example in production: landers-app (`apps/server/src/app-tools.ts`, `find_skill` / `use_skill` on the Claude Agent SDK; `apps/server/scripts/build.mjs` copies the data files).
package/docs/setup.md ADDED
@@ -0,0 +1,278 @@
1
+ # skill-router setup guide
2
+
3
+ skill-router gives your AI coding agent the right expert skill for each task, from a catalog of 256 web-design skills plus any skills you already have. You don't install them all: the agent sees a short list of the skills that fit, and loads only the one it picks.
4
+
5
+ **Start with the section for the tool you use.** Section 1 (Claude Code in VS Code) is the recommended setup.
6
+
7
+ | You use | Section | How automatic |
8
+ |---|---|---|
9
+ | **Claude Code in VS Code** | [1](#1-claude-code-in-vs-code-recommended) | Fully automatic: every prompt is routed |
10
+ | Claude Code in a terminal | [2](#2-claude-code-in-a-terminal) | Fully automatic |
11
+ | Claude Desktop app | [3](#3-claude-desktop) | The model calls it when it sees fit (one line of setup makes this reliable) |
12
+ | VS Code with GitHub Copilot | [4](#4-vs-code-with-github-copilot-agent-mode) | Same as Desktop |
13
+ | Cursor | [5](#5-cursor) | Same as Desktop |
14
+ | Windsurf | [6](#6-windsurf) | Same as Desktop |
15
+ | OpenAI Codex CLI | [7](#7-openai-codex-cli) | Same as Desktop |
16
+ | Gemini CLI | [8](#8-gemini-cli) | Same as Desktop |
17
+ | Anything else that supports MCP | [9](#9-any-other-mcp-client) | Same as Desktop |
18
+ | Your own app or agent | [docs/integrate.md](integrate.md) | You decide |
19
+
20
+ ---
21
+
22
+ ## 0. Before you start (every platform)
23
+
24
+ You need **Node.js 22 or newer**. Check in a terminal:
25
+
26
+ ```sh
27
+ node -v # should print v22.x or higher
28
+ ```
29
+
30
+ If it's missing or older, install the LTS version from <https://nodejs.org> (or `brew install node` on a Mac), then open a new terminal.
31
+
32
+ **On Windows, also install [Git for Windows](https://git-scm.com/download/win).** Claude Code runs plugin hooks in Git Bash. Without it they run in PowerShell, and skill-router's automatic routing won't work.
33
+
34
+ **Optional, but makes every prompt faster:** install the router once globally. The Claude Code plugin then uses it directly instead of going through `npx`, which takes under 0.1 s per prompt instead of about 0.3 s.
35
+
36
+ ```sh
37
+ npm i -g @originkit/skillrouter
38
+ skill-router route "our pricing page buttons feel flat" # quick test: prints a few matching skills
39
+ ```
40
+
41
+ ---
42
+
43
+ ## 1. Claude Code in VS Code (recommended)
44
+
45
+ ### Step 1: Install Claude Code in VS Code
46
+ 1. You need VS Code 1.94 or newer (**Code → About** / **Help → About**).
47
+ 2. Open **Extensions** (⇧⌘X on Mac, Ctrl+Shift+X on Windows/Linux), search for **Claude Code** (publisher **Anthropic**, ID `anthropic.claude-code`) and click **Install**.
48
+ 3. Open the Claude Code panel and sign in with your Claude account when asked.
49
+
50
+ ✅ **Check:** you can send Claude a message in the panel and get an answer.
51
+
52
+ The extension includes its own copy of Claude Code, so the chat panel works without anything else. Only the optional terminal route in step 2 needs the separate `claude` command.
53
+
54
+ ### Step 2: Install the skill-router plugin
55
+
56
+ **In the Claude Code panel (easiest):**
57
+ 1. Type `/plugins` in the prompt box and press Enter. The **Manage plugins** screen opens.
58
+ 2. Open the **Marketplaces** tab, add `landerdevelopers/skill-router`, and confirm.
59
+ 3. Open the **Plugins** tab, find **skill-router**, click **Install**, and choose the **User** scope so it works in every project.
60
+
61
+ **Or from a terminal** (VS Code: **Terminal → New Terminal**). This needs the `claude` command line; the extension doesn't add it to your terminal. Install it once from <https://code.claude.com/docs/en/setup> (on Mac or Linux: `curl -fsSL https://claude.ai/install.sh | bash`). Then:
62
+
63
+ ```sh
64
+ claude plugin marketplace add landerdevelopers/skill-router
65
+ claude plugin install skill-router@skill-router
66
+ ```
67
+
68
+ You should see `✔ Successfully installed plugin: skill-router@skill-router (scope: user)`. The extension and the terminal share plugins, so it's installed for both.
69
+
70
+ ### Step 3: Reload VS Code
71
+ Run **Developer: Reload Window** from the command palette (⇧⌘P / Ctrl+Shift+P), or just restart VS Code. Plugins load when a Claude Code session starts.
72
+
73
+ ### Step 4: Check that it works
74
+ In the Claude Code panel, try these three messages, each in a new chat:
75
+
76
+ | Type this | What should happen |
77
+ |---|---|
78
+ | `our pricing page buttons feel flat` | Claude loads a polish skill such as **make-interfaces-feel-better** before it starts working |
79
+ | `use the break-ui skill on the dashboard` | Claude follows the **break-ui** instructions straight away, because you named the skill |
80
+ | `write a bash one-liner to rename .jpeg files to .jpg` | No skill is used; Claude just answers |
81
+
82
+ Two more checks in the panel:
83
+ - Type `/mcp`. The skill-router server (shown as `plugin:skill-router:skill-router`) should say **Connected**.
84
+ - Type `/`, then choose **Hooks**. A **UserPromptSubmit** hook from skill-router should be listed. This view shows that the hook is loaded, not each time it runs; the three test messages above show it working.
85
+
86
+ ✅ If all three behave as described, you're done.
87
+
88
+ ### What happens from now on
89
+ - **Every message you send is routed automatically.** If skills fit, Claude gets a short list of them (about 300 tokens) and loads the best fit before it starts. If nothing fits, nothing is added.
90
+ - **To use a specific skill, just name it:** `/better-colors`, `use the seo-audit skill`, or `emilkowalski's animate skill`. A named skill is always loaded.
91
+ - **Skills you already have** in `~/.claude/skills` or in a project's `.claude/skills` folder are found automatically, and skills you install later are picked up right away. You don't need to reload.
92
+ - A skill's instructions are downloaded the first time it's used (about 0.5 s), then cached in `~/.cache/skill-router`.
93
+
94
+ ### Keep it up to date, or remove it
95
+ ```sh
96
+ claude plugin marketplace update skill-router # fetch the latest plugin definition
97
+ claude plugin update skill-router@skill-router
98
+ npm i -g @originkit/skillrouter@latest # only if you did the optional global install
99
+ claude plugin uninstall skill-router@skill-router # to remove
100
+ ```
101
+
102
+ ---
103
+
104
+ ## 2. Claude Code in a terminal
105
+
106
+ This uses the same plugin as section 1:
107
+
108
+ ```sh
109
+ claude plugin marketplace add landerdevelopers/skill-router
110
+ claude plugin install skill-router@skill-router
111
+ ```
112
+
113
+ Then start `claude` again and run the checks from [section 1, step 4](#step-4-check-that-it-works).
114
+
115
+ **Want the tools without the automatic routing?** Install only the MCP server, with no hook:
116
+ ```sh
117
+ claude mcp add skill-router -s user -- npx -y @originkit/skillrouter mcp
118
+ ```
119
+
120
+ ---
121
+
122
+ ## 3. Claude Desktop
123
+
124
+ **Option A: extension file.** Get `skill-router.mcpb` (ask whoever shared this guide, or build it with `npm run build:mcpb` in this repo). Then in Claude Desktop:
125
+ 1. Open **Settings → Desktop app**, and click **Manage** next to Extensions.
126
+ 2. Click **Advanced settings**, and in **Extension Developer** click **Install Extension…**.
127
+ 3. Pick `skill-router.mcpb`. If you like, choose an extra skills folder when asked.
128
+
129
+ **Option B: config file.** Open Claude Desktop's config file. It's usually `~/Library/Application Support/Claude/claude_desktop_config.json` on Mac or `%APPDATA%\Claude\claude_desktop_config.json` on Windows, and newer versions open it from **Settings → Developer → Edit Config**. Add this:
130
+
131
+ ```json
132
+ {
133
+ "mcpServers": {
134
+ "skill-router": { "command": "npx", "args": ["-y", "@originkit/skillrouter", "mcp"] }
135
+ }
136
+ }
137
+ ```
138
+
139
+ Save the file and restart Claude Desktop.
140
+
141
+ ✅ **Check:** the 🔌 / tools menu in a chat lists **skill-router** with `route_skill` and `get_skill`. Ask: *"Which skill should I use to fix flat-looking buttons? Use skill-router."*
142
+
143
+ Desktop doesn't route your messages automatically. For that, see [Making MCP-only tools use it reliably](#making-mcp-only-tools-use-it-reliably).
144
+
145
+ ---
146
+
147
+ ## 4. VS Code with GitHub Copilot (agent mode)
148
+
149
+ Create `.vscode/mcp.json` in your project, or add the same to your user settings:
150
+
151
+ ```json
152
+ {
153
+ "servers": {
154
+ "skill-router": { "type": "stdio", "command": "npx", "args": ["-y", "@originkit/skillrouter", "mcp"] }
155
+ }
156
+ }
157
+ ```
158
+
159
+ Open Copilot Chat, switch to **Agent** mode, and enable the **skill-router** tools in the tools picker. Then add the one-line rule (see below) to `.github/copilot-instructions.md`.
160
+
161
+ ---
162
+
163
+ ## 5. Cursor
164
+
165
+ Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
166
+
167
+ ```json
168
+ {
169
+ "mcpServers": {
170
+ "skill-router": { "command": "npx", "args": ["-y", "@originkit/skillrouter", "mcp"] }
171
+ }
172
+ }
173
+ ```
174
+
175
+ Check **Cursor Settings → MCP**: skill-router should show a green dot. Then add the one-line rule to `.cursor/rules` (or **Settings → Rules**).
176
+
177
+ ---
178
+
179
+ ## 6. Windsurf
180
+
181
+ Add the same `mcpServers` block as for Cursor to `~/.codeium/windsurf/mcp_config.json`, then refresh the MCP servers in Windsurf's Cascade panel. Add the one-line rule to your Windsurf rules.
182
+
183
+ ---
184
+
185
+ ## 7. OpenAI Codex CLI
186
+
187
+ Add this to `~/.codex/config.toml`:
188
+
189
+ ```toml
190
+ [mcp_servers.skill-router]
191
+ command = "npx"
192
+ args = ["-y", "@originkit/skillrouter", "mcp"]
193
+ ```
194
+
195
+ Then add the one-line rule to `AGENTS.md` in your project.
196
+
197
+ ---
198
+
199
+ ## 8. Gemini CLI
200
+
201
+ Add this to `~/.gemini/settings.json`:
202
+
203
+ ```json
204
+ { "mcpServers": { "skill-router": { "command": "npx", "args": ["-y", "@originkit/skillrouter", "mcp"] } } }
205
+ ```
206
+
207
+ Then add the one-line rule to `GEMINI.md`.
208
+
209
+ ---
210
+
211
+ ## 9. Any other MCP client
212
+
213
+ Use the same three values:
214
+ - **command:** `npx`
215
+ - **args:** `-y @originkit/skillrouter mcp`
216
+ - **transport:** stdio
217
+
218
+ The server provides two tools:
219
+ - `route_skill(task)` returns up to 40 candidate skills, one line each.
220
+ - `get_skill(id, file?)` returns a skill's instructions.
221
+
222
+ **Agents that read `SKILL.md` and can run shell commands** (for example Codex or Claude Code without the plugin) can instead install one small router skill:
223
+ ```sh
224
+ npx skills add https://github.com/landerdevelopers/skill-router --skill skill-router
225
+ ```
226
+
227
+ ---
228
+
229
+ ## Making MCP-only tools use it reliably
230
+
231
+ Only the Claude Code plugin (sections 1 and 2) routes every message automatically. In the other tools, the model decides when to call `route_skill`, and it often won't unless told to. Add this line to the tool's instructions file: `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md`, `GEMINI.md`, or your Windsurf rules:
232
+
233
+ ```
234
+ 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.
235
+ ```
236
+
237
+ ---
238
+
239
+ ## Options (all platforms)
240
+
241
+ Add these to the `args` of an MCP setup, or to `skill-router` on the command line:
242
+
243
+ | Option | What it does |
244
+ |---|---|
245
+ | `--skills <folder>` | Also route over the `SKILL.md` skills in this folder. You can repeat it |
246
+ | `--no-pack` | Leave out the bundled 256-skill web-design catalog and use only your own skills |
247
+ | `--no-discover` | Don't scan `~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, `~/.cursor/skills` or the project's equivalents |
248
+
249
+ ---
250
+
251
+ ## Troubleshooting
252
+
253
+ | Symptom | Fix |
254
+ |---|---|
255
+ | `skill-router: command not found` when running `npx @originkit/skillrouter` **inside the skill-router repo itself** | Expected: inside its own repo, npx uses the repo instead of npm. Run it from any other folder, or use `node src/cli.ts` there |
256
+ | `node: command not found`, or errors about syntax or `import` | Node is missing or older than 22. See [section 0](#0-before-you-start-every-platform) |
257
+ | Claude Code doesn't seem to use skills | Run `claude plugin list` (skill-router should show **enabled**), then reload the window. Try `use the break-ui skill on …`: a named skill is always loaded |
258
+ | The first message after installing is slow | `npx` downloads the package once. Do the optional global install from [section 0](#0-before-you-start-every-platform) to remove this delay for good |
259
+ | `get_skill` fails or times out | Skill instructions download from `raw.githubusercontent.com` the first time. Check that your network or VPN allows it |
260
+ | An MCP tool shows skill-router as failed or disconnected | Run `npx -y @originkit/skillrouter route "test"` in a terminal. If that fails, the error tells you what's wrong (usually the Node version or network) |
261
+ | Windows: Claude Code doesn't route automatically | Install Git for Windows (see [section 0](#0-before-you-start-every-platform)) and restart. Claude Code runs plugin hooks in Git Bash, and they fail under PowerShell. The MCP-only setup from section 2 works without it |
262
+ | VS Code: a slash command from the docs isn't available | The extension has most but not all built-in commands. Use the terminal route in step 2 |
263
+
264
+ ---
265
+
266
+ ## What's been tested
267
+
268
+ | Platform | Status |
269
+ |---|---|
270
+ | Claude Code, terminal and plugin | ✅ Installed from the GitHub marketplace and run in real sessions (40-prompt benchmark) |
271
+ | Claude Code in VS Code | ⚠️ Uses the same plugins, hooks and MCP settings as the terminal, per Claude Code's docs. Not yet tried in the VS Code panel by us: the three checks in section 1, step 4 confirm it |
272
+ | MCP server (all MCP clients) | ✅ Protocol tested: `tools/list`, `route_skill`, `get_skill` |
273
+ | Claude Desktop `.mcpb` | ⚠️ Bundle validated and its server tested; install through Settings not yet tried |
274
+ | Copilot, Cursor, Windsurf, Codex, Gemini CLI configs | ⚠️ Written to each tool's documented format; not yet run inside each tool |
275
+ | Windows | ⚠️ Not tested |
276
+ | `npx skills add …` router skill (section 9) | ⚠️ Not tested |
277
+
278
+ Found a problem or a step that didn't match? Open an issue at <https://github.com/landerdevelopers/skill-router/issues>.
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "@originkit/skillrouter",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Pick the right agent skill for a task, from 2 skills to 200. Library, CLI and MCP server; works with any harness.",
5
+ "main": "./dist/index.js",
6
+ "scripts": {
7
+ "build": "tsc",
8
+ "test": "node --test test/*.test.ts",
9
+ "eval": "node test/eval.ts",
10
+ "prepublishOnly": "npm run build",
11
+ "build:mcpb": "bash mcpb/build.sh"
12
+ },
13
+ "license": "MIT",
14
+ "type": "module",
15
+ "dependencies": {
16
+ "@modelcontextprotocol/sdk": "^1.32.2",
17
+ "minisearch": "^7.2.0",
18
+ "yaml": "^2.9.1",
19
+ "zod": "^4.6.7"
20
+ },
21
+ "devDependencies": {
22
+ "@types/node": "^26.6.6",
23
+ "typescript": "^7.0.2"
24
+ },
25
+ "types": "./dist/index.d.ts",
26
+ "exports": {
27
+ ".": {
28
+ "types": "./dist/index.d.ts",
29
+ "default": "./dist/index.js"
30
+ }
31
+ },
32
+ "bin": {
33
+ "skill-router": "dist/cli.js"
34
+ },
35
+ "files": [
36
+ "dist",
37
+ "data/skills.json",
38
+ "data/keywords.json",
39
+ "docs/integrate.md",
40
+ "docs/setup.md"
41
+ ],
42
+ "engines": {
43
+ "node": ">=22.18"
44
+ },
45
+ "publishConfig": {
46
+ "access": "public"
47
+ },
48
+ "repository": {
49
+ "type": "git",
50
+ "url": "git+https://github.com/landerdevelopers/skill-router.git"
51
+ },
52
+ "author": "landerstudio"
53
+ }