@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/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,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@originkit/skillrouter",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
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
5
|
"main": "./dist/index.js",
|
|
6
6
|
"scripts": {
|
|
@@ -34,7 +34,10 @@
|
|
|
34
34
|
},
|
|
35
35
|
"files": [
|
|
36
36
|
"dist",
|
|
37
|
-
"data/skills.json"
|
|
37
|
+
"data/skills.json",
|
|
38
|
+
"data/keywords.json",
|
|
39
|
+
"docs/integrate.md",
|
|
40
|
+
"docs/setup.md"
|
|
38
41
|
],
|
|
39
42
|
"engines": {
|
|
40
43
|
"node": ">=22.18"
|