@originkit/skillrouter 0.1.2 → 0.1.4
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/CHANGELOG.md +27 -0
- package/README.md +8 -0
- package/data/keywords.json +0 -75
- package/data/skills.json +0 -42
- package/dist/cli.js +12 -5
- package/dist/mcp.js +1 -1
- package/docs/integrate.md +4 -4
- package/docs/setup.md +27 -11
- package/package.json +5 -3
- package/plugin/.claude-plugin/plugin.json +3 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.4
|
|
4
|
+
- **Fix: Claude Code now loads suggested skills reliably.** The hook told Claude to "use the installed skill", which sent it to Claude Code's Skill tool with a full id ("Unknown skill") or to skills Claude Code never loads, and it then skipped skills altogether. Every suggestion now loads through `get_skill`, which also reads installed skills from disk, and names the exact tool. In real sessions, Claude loaded the right skill before editing in 16/16 runs (it was 0/3).
|
|
5
|
+
- **Named skills:** the injected instructions say they're already loaded, so Claude doesn't fetch them again.
|
|
6
|
+
- **The plugin's MCP server and `npx` fallback are pinned to the plugin's own version.**
|
|
7
|
+
- **Setup guide:** Cursor needs MCP approval and uses `.cursor/rules/*.mdc`, Gemini only runs MCP servers in trusted folders, there's a one-command Codex setup, troubleshooting for a server that shows as disconnected on first start, and an updated "what's been tested" table.
|
|
8
|
+
- **From 0.1.3, which shipped before its doc updates:** the README "What's included" section, `integrate.md` saying 0.1.3 or later, and this changelog in the package.
|
|
9
|
+
|
|
10
|
+
## 0.1.3
|
|
11
|
+
- **Catalog:** removed 3 skills whose instructions no longer exist upstream (`image-taste-frontend`, `rams` (repo deleted), `seo-strategy`). The catalog is 253 skills (252 routable), and every one's instructions load.
|
|
12
|
+
- **New `npm run release-check`:** packs the repo, installs it fresh, and runs 67 checks of what users get: package contents, every skill's instructions, routing, the CLI, the hook, the MCP server, and the library.
|
|
13
|
+
- **Docs:** a "What's included" section in the README, and this changelog.
|
|
14
|
+
|
|
15
|
+
## 0.1.2
|
|
16
|
+
- **The Claude Code plugin ships inside the npm package,** so installing it doesn't need GitHub: `npm i -g @originkit/skillrouter` → `claude plugin marketplace add "$(npm root -g)/@originkit/skillrouter"` → `claude plugin install skill-router@skill-router`.
|
|
17
|
+
- **Setup guide and README** use npm-based installs only. Doc links point to public copies on unpkg.
|
|
18
|
+
|
|
19
|
+
## 0.1.1
|
|
20
|
+
- **Problem keywords per skill** (`data/keywords.json`). On blind prompts, the right skill is in the top 40 for 98% of tasks (was 83%).
|
|
21
|
+
- **Claude Code hook:** up to 8 candidates at confidence ≥ 0.15, worded so Claude loads the best fit first. Named skills have their full instructions injected. The MCP tools are always loaded, so there's no `ToolSearch` turn.
|
|
22
|
+
- **`RouteResult.confidence`**, 40 default rerank candidates, renamed-skill redirects (`replacedBy`), merging of installed copies into their catalog entry, and auto-discovery of installed skills.
|
|
23
|
+
- **Docs:** setup guide for every platform (`docs/setup.md`), integration guide for apps and agents (`docs/integrate.md`).
|
|
24
|
+
- **Benchmark** (`bench/`): in real Claude Code sessions, the router loaded a useful skill for 77% of tasks, against 39% with every skill installed natively.
|
|
25
|
+
|
|
26
|
+
## 0.1.0
|
|
27
|
+
- **First release:** BM25 routing over SKILL.md metadata with a no-fit check, optional model rerank, a CLI, an MCP server, a Claude Code plugin, and a web-design catalog.
|
package/README.md
CHANGED
|
@@ -11,6 +11,13 @@ It works with any skill in the open `SKILL.md` format, and with any harness: a C
|
|
|
11
11
|
|
|
12
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.
|
|
13
13
|
|
|
14
|
+
## What's included
|
|
15
|
+
|
|
16
|
+
- **253 web-design skills, ready to route.** They come from a curated list (revamps, typography, colour, copy, layout, motion, imagery, accessibility, SEO, performance, conversion, showpieces), deduplicated by `owner/repo/skill`. For each skill, the package ships what's needed to choose it: name, description, summary, category and tier, audit warnings, and problem keywords (`data/skills.json`, `data/keywords.json`, about 430 kB).
|
|
17
|
+
- **Each skill's full instructions** (its `SKILL.md`) are not bundled. They're fetched from the skill's own repo the first time it's picked, pinned to an exact commit, then cached. The release check confirms all of them load.
|
|
18
|
+
- **Skills that moved upstream** (22) still load from their pinned commit and carry a caution. One renamed skill (`schema-markup`) routes to its successor (`schema`), so 252 are routable.
|
|
19
|
+
- **Your own skills** are added automatically (`~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, `~/.cursor/skills` and the project's equivalents), or with `--skills <folder>`. Use `--no-pack` to route over only yours.
|
|
20
|
+
|
|
14
21
|
## Install
|
|
15
22
|
|
|
16
23
|
**Full step-by-step for every tool: [setup guide](https://unpkg.com/@originkit/skillrouter/docs/setup.md).** Quick start:
|
|
@@ -101,6 +108,7 @@ Inside this repo, `npx @originkit/skillrouter` resolves to the repo itself, not
|
|
|
101
108
|
|
|
102
109
|
```sh
|
|
103
110
|
npm test # unit tests (fixtures in test/fixtures)
|
|
111
|
+
npm run release-check # pack + install fresh + 69 checks of what users get (fetches every skill's instructions)
|
|
104
112
|
npm run eval # routing quality on data/eval.json; add -- --sweep to calibrate thresholds
|
|
105
113
|
npm run eval -- --file data/eval-holdout.json --rerank # blind set; --rerank also scores a small-model pick (uses claude -p)
|
|
106
114
|
npm run build
|
package/data/keywords.json
CHANGED
|
@@ -153,27 +153,6 @@
|
|
|
153
153
|
"bespoke look",
|
|
154
154
|
"original concept"
|
|
155
155
|
],
|
|
156
|
-
"leonxlnx/taste-skill/image-taste-frontend": [
|
|
157
|
-
"image heavy",
|
|
158
|
-
"photo first",
|
|
159
|
-
"pictures look weak",
|
|
160
|
-
"visuals drive layout",
|
|
161
|
-
"photography focus",
|
|
162
|
-
"photo led",
|
|
163
|
-
"image centered",
|
|
164
|
-
"big photos",
|
|
165
|
-
"art direction",
|
|
166
|
-
"gallery look",
|
|
167
|
-
"imagery feels random",
|
|
168
|
-
"image layout",
|
|
169
|
-
"stock photos",
|
|
170
|
-
"visual first",
|
|
171
|
-
"photo composition",
|
|
172
|
-
"image grid",
|
|
173
|
-
"full bleed images",
|
|
174
|
-
"photo sizing",
|
|
175
|
-
"picture quality"
|
|
176
|
-
],
|
|
177
156
|
"onewave-ai/claude-skills/landing-page-copywriter": [
|
|
178
157
|
"words are weak",
|
|
179
158
|
"copy isnt convincing",
|
|
@@ -3394,33 +3373,6 @@
|
|
|
3394
3373
|
"over engineered ui",
|
|
3395
3374
|
"keep it simple"
|
|
3396
3375
|
],
|
|
3397
|
-
"brianlovin/agent-config/rams": [
|
|
3398
|
-
"visual problems review",
|
|
3399
|
-
"design engineer check",
|
|
3400
|
-
"accessibility and visual bugs",
|
|
3401
|
-
"ui critique",
|
|
3402
|
-
"spacing issues check",
|
|
3403
|
-
"contrast and layout review",
|
|
3404
|
-
"review my interface",
|
|
3405
|
-
"visual bug hunt",
|
|
3406
|
-
"design code review",
|
|
3407
|
-
"polish my ui",
|
|
3408
|
-
"ui looks off",
|
|
3409
|
-
"rams review",
|
|
3410
|
-
"design qa",
|
|
3411
|
-
"pixel problems",
|
|
3412
|
-
"visual accessibility check",
|
|
3413
|
-
"ui feedback",
|
|
3414
|
-
"dieter rams",
|
|
3415
|
-
"interface audit",
|
|
3416
|
-
"design checklist",
|
|
3417
|
-
"visual regressions",
|
|
3418
|
-
"layout review",
|
|
3419
|
-
"ugly ui",
|
|
3420
|
-
"design sanity check",
|
|
3421
|
-
"look over my design",
|
|
3422
|
-
"component review"
|
|
3423
|
-
],
|
|
3424
3376
|
"mindrally/skills/accessibility-a11y": [
|
|
3425
3377
|
"inclusive design",
|
|
3426
3378
|
"accessible components",
|
|
@@ -3903,33 +3855,6 @@
|
|
|
3903
3855
|
"metadata for each route",
|
|
3904
3856
|
"preview card looks plain"
|
|
3905
3857
|
],
|
|
3906
|
-
"kostja94/marketing-skills/seo-strategy": [
|
|
3907
|
-
"what to fix first",
|
|
3908
|
-
"where to start with seo",
|
|
3909
|
-
"seo priorities",
|
|
3910
|
-
"too many seo tasks",
|
|
3911
|
-
"overwhelmed by seo",
|
|
3912
|
-
"which seo task matters most",
|
|
3913
|
-
"seo to do list",
|
|
3914
|
-
"biggest seo wins",
|
|
3915
|
-
"order of seo steps",
|
|
3916
|
-
"seo roadmap",
|
|
3917
|
-
"no idea where to begin search",
|
|
3918
|
-
"quick search wins",
|
|
3919
|
-
"cut through seo noise",
|
|
3920
|
-
"what matters most for ranking",
|
|
3921
|
-
"seo plan",
|
|
3922
|
-
"prioritise search work",
|
|
3923
|
-
"stop chasing every seo tip",
|
|
3924
|
-
"search visibility plan",
|
|
3925
|
-
"seo checklist order",
|
|
3926
|
-
"long term search strategy",
|
|
3927
|
-
"not sure what to tackle",
|
|
3928
|
-
"focus my seo effort",
|
|
3929
|
-
"impact versus effort search",
|
|
3930
|
-
"search growth steps",
|
|
3931
|
-
"where should my effort go"
|
|
3932
|
-
],
|
|
3933
3858
|
"claude-office-skills/skills/seo-optimizer": [
|
|
3934
3859
|
"keyword ideas",
|
|
3935
3860
|
"what should i target",
|
package/data/skills.json
CHANGED
|
@@ -134,20 +134,6 @@
|
|
|
134
134
|
"install": "npx skills add https://github.com/bencium/bencium-marketplace --skill bencium-innovative-ux-designer",
|
|
135
135
|
"source": "https://raw.githubusercontent.com/bencium/bencium-marketplace/5de46a39b4640fa419560cd0b67e4c4b50dac802/bencium-innovative-ux-designer/skills/bencium-innovative-ux-designer/SKILL.md"
|
|
136
136
|
},
|
|
137
|
-
{
|
|
138
|
-
"id": "leonxlnx/taste-skill/image-taste-frontend",
|
|
139
|
-
"name": "image-taste-frontend",
|
|
140
|
-
"description": "Image-first website design: art-directs the visuals, then builds the page around them.",
|
|
141
|
-
"repo": "leonxlnx/taste-skill",
|
|
142
|
-
"summary": "Image-first website design: art-directs the visuals, then builds the page around them.",
|
|
143
|
-
"placements": [
|
|
144
|
-
{
|
|
145
|
-
"category": "hero-revamp",
|
|
146
|
-
"tier": "good"
|
|
147
|
-
}
|
|
148
|
-
],
|
|
149
|
-
"install": "npx skills add https://github.com/leonxlnx/taste-skill --skill image-taste-frontend"
|
|
150
|
-
},
|
|
151
137
|
{
|
|
152
138
|
"id": "onewave-ai/claude-skills/landing-page-copywriter",
|
|
153
139
|
"name": "landing-page-copywriter",
|
|
@@ -2190,20 +2176,6 @@
|
|
|
2190
2176
|
"install": "npx skills add https://github.com/wondelai/skills --skill steve-jobs-design-review",
|
|
2191
2177
|
"source": "https://raw.githubusercontent.com/wondelai/skills/c5265583b1a9740f06831e1d3e89b35bba3eb430/steve-jobs-design-review/SKILL.md"
|
|
2192
2178
|
},
|
|
2193
|
-
{
|
|
2194
|
-
"id": "brianlovin/agent-config/rams",
|
|
2195
|
-
"name": "rams",
|
|
2196
|
-
"description": "A design-engineer review for accessibility and visual issues.",
|
|
2197
|
-
"repo": "brianlovin/agent-config",
|
|
2198
|
-
"summary": "A design-engineer review for accessibility and visual issues.",
|
|
2199
|
-
"placements": [
|
|
2200
|
-
{
|
|
2201
|
-
"category": "review-qa-and-accessibility",
|
|
2202
|
-
"tier": "good"
|
|
2203
|
-
}
|
|
2204
|
-
],
|
|
2205
|
-
"install": "npx skills add https://github.com/brianlovin/agent-config --skill rams"
|
|
2206
|
-
},
|
|
2207
2179
|
{
|
|
2208
2180
|
"id": "mindrally/skills/accessibility-a11y",
|
|
2209
2181
|
"name": "accessibility-a11y",
|
|
@@ -2501,20 +2473,6 @@
|
|
|
2501
2473
|
"install": "npx skills add https://github.com/laguagu/claude-code-nextjs-skills --skill nextjs-seo",
|
|
2502
2474
|
"source": "https://raw.githubusercontent.com/laguagu/claude-code-nextjs-skills/b84dc5df467ce6c21e96f5266f8a3889c060e827/skills/nextjs-seo/SKILL.md"
|
|
2503
2475
|
},
|
|
2504
|
-
{
|
|
2505
|
-
"id": "kostja94/marketing-skills/seo-strategy",
|
|
2506
|
-
"name": "seo-strategy",
|
|
2507
|
-
"description": "Order and priorities for SEO work.",
|
|
2508
|
-
"repo": "kostja94/marketing-skills",
|
|
2509
|
-
"summary": "Order and priorities for SEO work.",
|
|
2510
|
-
"placements": [
|
|
2511
|
-
{
|
|
2512
|
-
"category": "seo",
|
|
2513
|
-
"tier": "good"
|
|
2514
|
-
}
|
|
2515
|
-
],
|
|
2516
|
-
"install": "npx skills add https://github.com/kostja94/marketing-skills --skill seo-strategy"
|
|
2517
|
-
},
|
|
2518
2476
|
{
|
|
2519
2477
|
"id": "claude-office-skills/skills/seo-optimizer",
|
|
2520
2478
|
"name": "seo-optimizer",
|
package/dist/cli.js
CHANGED
|
@@ -42,6 +42,11 @@ if (!cmd || values.help) {
|
|
|
42
42
|
process.exit(cmd || values.help ? 0 : 1);
|
|
43
43
|
}
|
|
44
44
|
const CACHE = join(homedir(), ".cache", "skill-router");
|
|
45
|
+
// The hook ships in the Claude Code plugin, so the tool's full name is known; naming it saves the turn Claude
|
|
46
|
+
// otherwise spends guessing it. Loading via get_skill (never "use the installed skill") took live runs from
|
|
47
|
+
// 0/3 to 12/12 loads before editing (test-reports/claude-code.md, then the wording runs).
|
|
48
|
+
const GET_SKILL = "mcp__plugin_skill-router_skill-router__get_skill";
|
|
49
|
+
const HOOK_LEAD = `skill-router: these skills match this request (already routed, so route_skill isn't needed). As your first step, before reading or searching any files, pick the one that best fits the task (not necessarily the first; the list is ranked by word overlap), load it with the get_skill tool (${GET_SKILL}, id = its id below) and follow it. Skip this only if none of them is about this task.`;
|
|
45
50
|
// Below this RouteResult.confidence the hook stays silent.
|
|
46
51
|
const HOOK_MIN = 0.15;
|
|
47
52
|
if (cmd === "mcp") {
|
|
@@ -60,16 +65,18 @@ else if (cmd === "hook") {
|
|
|
60
65
|
// Unsolicited, so stricter than route_skill: weak matches stay silent.
|
|
61
66
|
if (res && !res.none && res.confidence >= HOOK_MIN) {
|
|
62
67
|
const parts = [];
|
|
63
|
-
|
|
68
|
+
// Always get_skill with the full id: it reads installed skills from disk too. "Use the installed skill" sent
|
|
69
|
+
// Claude to its Skill tool with the full id (unknown skill), or to skills found in folders Claude Code never loads.
|
|
70
|
+
const how = (s) => `load it with the get_skill tool (${GET_SKILL}), id "${s.id}"`;
|
|
64
71
|
const caution = (s) => (s.warnings?.length ? ` Caution: ${s.warnings.join("; ")}; tell the user before relying on it.` : "");
|
|
65
72
|
// Named by the user: load the instructions now instead of suggesting them.
|
|
66
73
|
for (const { skill: s } of res.matches.filter((m) => m.mentioned)) {
|
|
67
74
|
const body = await loadSkillBody(s, { cacheDir: CACHE }).catch(() => null);
|
|
68
75
|
const files = s.path
|
|
69
76
|
? `Files it refers to are next to it in ${dirname(s.path)}.`
|
|
70
|
-
: `Files it refers to (e.g. references/…): the get_skill tool with id "${s.id}" and file "<path>".`;
|
|
77
|
+
: `Files it refers to (e.g. references/…): the get_skill tool (${GET_SKILL}) with id "${s.id}" and file "<path>".`;
|
|
71
78
|
parts.push(body
|
|
72
|
-
? `skill-router: the user asked for the ${s.name} skill (${s.id}).
|
|
79
|
+
? `skill-router: the user asked for the ${s.name} skill (${s.id}). Its instructions are below, already loaded (don't fetch it again): follow them for this request. ${files}${caution(s)}\n<skill id="${s.id}">\n${clip(body, 30_000)}\n</skill>`
|
|
73
80
|
: `skill-router: the user asked for the ${s.name} skill (${s.id}); ${how(s)}.${caution(s)}`);
|
|
74
81
|
}
|
|
75
82
|
// Otherwise a short list for Claude to judge. Word matching alone is right first only about half the time on
|
|
@@ -80,9 +87,9 @@ else if (cmd === "hook") {
|
|
|
80
87
|
// No "strong match" tag here: on unseen prompts word matching's first pick is wrong ~1 in 3, and a tag biases Claude toward it.
|
|
81
88
|
const lines = suggested.map(({ skill: s }) => {
|
|
82
89
|
const about = (s.summary ?? s.description).replace(/\s+/g, " ").slice(0, 160);
|
|
83
|
-
return `- ${s.id}: ${about}${
|
|
90
|
+
return `- ${s.id}: ${about}${caution(s)}`;
|
|
84
91
|
});
|
|
85
|
-
parts.push(
|
|
92
|
+
parts.push(HOOK_LEAD + `\n${lines.join("\n")}`);
|
|
86
93
|
}
|
|
87
94
|
const additionalContext = parts.join("\n\n");
|
|
88
95
|
console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext } }));
|
package/dist/mcp.js
CHANGED
|
@@ -10,7 +10,7 @@ const text = (t) => ({ content: [{ type: "text", text: t }] });
|
|
|
10
10
|
export async function serve(load, cacheDir) {
|
|
11
11
|
// Rebuilt per call (tens of ms) so skills installed while the server runs are seen at once.
|
|
12
12
|
const router = () => createRouter(load());
|
|
13
|
-
const server = new McpServer({ name: "skill-router", version: "0.1.
|
|
13
|
+
const server = new McpServer({ name: "skill-router", version: "0.1.4" }, {
|
|
14
14
|
instructions: "Before starting a substantial task, call route_skill with the user's task to see whether a specialised skill covers it. If a returned skill genuinely fits, load it with get_skill and follow it. If none fits, carry on without one.",
|
|
15
15
|
});
|
|
16
16
|
server.registerTool("route_skill", {
|
package/docs/integrate.md
CHANGED
|
@@ -6,7 +6,7 @@ This guide is written so that a person, or a coding agent (Claude Code, Cursor,
|
|
|
6
6
|
|
|
7
7
|
## What you're adding
|
|
8
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
|
|
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 253 web-design skills, and you can add your own. For each task, it does three things:
|
|
10
10
|
|
|
11
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
12
|
2. **Lets a model pick** from the shortlist: either your agent itself, or a cheap model you plug in.
|
|
@@ -29,7 +29,7 @@ Word matching is good at getting the right skill *into* the list, and a model is
|
|
|
29
29
|
npm i @originkit/skillrouter # Node ≥ 22, ESM (CommonJS require() also works)
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
Use version **0.1.
|
|
32
|
+
Use version **0.1.3 or later**: it has the problem keywords, `confidence`, the 40-candidate default, and a catalog in which every skill's instructions load.
|
|
33
33
|
|
|
34
34
|
✅ Check: `node -e 'import("@originkit/skillrouter").then(m => console.log(Object.keys(m)))'` lists `createRouter`, `loadPack` and `loadSkillBody`.
|
|
35
35
|
|
|
@@ -40,7 +40,7 @@ import { createRouter, loadPack, loadSkillsDir, loadSkillBody } from "@originkit
|
|
|
40
40
|
|
|
41
41
|
// Once per process, not per request.
|
|
42
42
|
export const router = createRouter([
|
|
43
|
-
...loadPack(), // the bundled
|
|
43
|
+
...loadPack(), // the bundled 253 web-design skills (+ their keywords)
|
|
44
44
|
// ...loadSkillsDir("./skills"), // optional: your own SKILL.md folders
|
|
45
45
|
// ...skillsFromDb, // optional: { id, name, description, source?, keywords? }[]
|
|
46
46
|
]);
|
|
@@ -206,7 +206,7 @@ The pack's data files are resolved relative to the library's own `dist/` folder:
|
|
|
206
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
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
208
|
|
|
209
|
-
✅ Check: in the built and deployed artifact, run `router.skills.length` (it should be
|
|
209
|
+
✅ Check: in the built and deployed artifact, run `router.skills.length` (it should be 252 plus your own: 253 catalog entries, one renamed skill folded into its successor) and `router.skills.some(s => s.keywords?.length)` (it should be `true`).
|
|
210
210
|
|
|
211
211
|
## Step 6: Test it
|
|
212
212
|
|
package/docs/setup.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# skill-router setup guide
|
|
2
2
|
|
|
3
|
-
skill-router gives your AI coding agent the right expert skill for each task, from a catalog of
|
|
3
|
+
skill-router gives your AI coding agent the right expert skill for each task, from a catalog of 253 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
4
|
|
|
5
5
|
**Start with the section for the tool you use.** Section 1 (Claude Code in VS Code) is the recommended setup.
|
|
6
6
|
|
|
@@ -79,7 +79,7 @@ In the Claude Code panel, try these three messages, each in a new chat:
|
|
|
79
79
|
| Type this | What should happen |
|
|
80
80
|
|---|---|
|
|
81
81
|
| `our pricing page buttons feel flat` | Claude loads a polish skill such as **make-interfaces-feel-better** before it starts working |
|
|
82
|
-
| `use the break-ui skill on
|
|
82
|
+
| `use the break-ui skill on <a page or component in your project>` | Claude follows the **break-ui** instructions straight away, because you named the skill |
|
|
83
83
|
| `write a bash one-liner to rename .jpeg files to .jpg` | No skill is used; Claude just answers |
|
|
84
84
|
|
|
85
85
|
Two more checks in the panel:
|
|
@@ -89,7 +89,7 @@ Two more checks in the panel:
|
|
|
89
89
|
✅ If all three behave as described, you're done.
|
|
90
90
|
|
|
91
91
|
### What happens from now on
|
|
92
|
-
- **Every message you send is routed automatically.**
|
|
92
|
+
- **Every message you send is routed automatically.** When skills match, Claude gets a short list of them (about 400 tokens), picks the best fit, and loads it before it starts working. Sometimes the list includes skills that don't fit, for example on a plain coding question; Claude ignores those. Chit-chat ("thanks", "continue") adds nothing.
|
|
93
93
|
- **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.
|
|
94
94
|
- **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.
|
|
95
95
|
- A skill's instructions are downloaded the first time it's used (about 0.5 s), then cached in `~/.cache/skill-router`.
|
|
@@ -175,7 +175,17 @@ Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one proje
|
|
|
175
175
|
}
|
|
176
176
|
```
|
|
177
177
|
|
|
178
|
-
|
|
178
|
+
Cursor asks you to approve a project's MCP servers before it starts them: turn skill-router on in **Cursor Settings → MCP**. It should then show a green dot. In the `cursor-agent` CLI, run `cursor-agent mcp enable skill-router` or pass `--approve-mcps`; `cursor-agent mcp list` should then show `skill-router: ready`.
|
|
179
|
+
|
|
180
|
+
Then add the one-line rule as a rule file. `.cursor/rules/` is a folder of `.mdc` files, so create `.cursor/rules/skill-router.mdc`:
|
|
181
|
+
|
|
182
|
+
```
|
|
183
|
+
---
|
|
184
|
+
description: Route design/copy/SEO/accessibility/performance/motion work through skill-router
|
|
185
|
+
alwaysApply: true
|
|
186
|
+
---
|
|
187
|
+
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.
|
|
188
|
+
```
|
|
179
189
|
|
|
180
190
|
---
|
|
181
191
|
|
|
@@ -195,19 +205,21 @@ command = "npx"
|
|
|
195
205
|
args = ["-y", "@originkit/skillrouter", "mcp"]
|
|
196
206
|
```
|
|
197
207
|
|
|
208
|
+
Or add it with one command: `codex mcp add skill-router -- npx -y @originkit/skillrouter mcp`. Check with `codex mcp get skill-router`.
|
|
209
|
+
|
|
198
210
|
Then add the one-line rule to `AGENTS.md` in your project.
|
|
199
211
|
|
|
200
212
|
---
|
|
201
213
|
|
|
202
214
|
## 8. Gemini CLI
|
|
203
215
|
|
|
204
|
-
Add this to `~/.gemini/settings.json
|
|
216
|
+
Add this to `~/.gemini/settings.json` (all projects) or `.gemini/settings.json` (one project):
|
|
205
217
|
|
|
206
218
|
```json
|
|
207
219
|
{ "mcpServers": { "skill-router": { "command": "npx", "args": ["-y", "@originkit/skillrouter", "mcp"] } } }
|
|
208
220
|
```
|
|
209
221
|
|
|
210
|
-
Then add the one-line rule to `GEMINI.md`.
|
|
222
|
+
Gemini CLI only starts MCP servers in folders you trust. Trust the folder when Gemini asks (or use `/permissions`); otherwise it disables every MCP server there. Check with `gemini mcp list`: skill-router should show `✓ … Connected`. Then add the one-line rule to `GEMINI.md`.
|
|
211
223
|
|
|
212
224
|
---
|
|
213
225
|
|
|
@@ -232,7 +244,7 @@ cp -R "$(npm root -g)/@originkit/skillrouter/skills/skill-router" ~/.agents/skil
|
|
|
232
244
|
|
|
233
245
|
## Making MCP-only tools use it reliably
|
|
234
246
|
|
|
235
|
-
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
|
|
247
|
+
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/skill-router.mdc` (see [section 5](#5-cursor)), `.github/copilot-instructions.md`, `GEMINI.md`, or your Windsurf rules:
|
|
236
248
|
|
|
237
249
|
```
|
|
238
250
|
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.
|
|
@@ -247,7 +259,7 @@ Add these to the `args` of an MCP setup, or to `skill-router` on the command lin
|
|
|
247
259
|
| Option | What it does |
|
|
248
260
|
|---|---|
|
|
249
261
|
| `--skills <folder>` | Also route over the `SKILL.md` skills in this folder. You can repeat it |
|
|
250
|
-
| `--no-pack` | Leave out the bundled
|
|
262
|
+
| `--no-pack` | Leave out the bundled 253-skill web-design catalog and use only your own skills |
|
|
251
263
|
| `--no-discover` | Don't scan `~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, `~/.cursor/skills` or the project's equivalents |
|
|
252
264
|
|
|
253
265
|
---
|
|
@@ -261,7 +273,10 @@ Add these to the `args` of an MCP setup, or to `skill-router` on the command lin
|
|
|
261
273
|
| 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 |
|
|
262
274
|
| 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 |
|
|
263
275
|
| `get_skill` fails or times out | Skill instructions download from `raw.githubusercontent.com` the first time. Check that your network or VPN allows it |
|
|
276
|
+
| An MCP tool shows skill-router as **disconnected the first time**, then connected later | The first start downloads the package through `npx`, which can be slower than the tool's startup timeout. Run `npx -y @originkit/skillrouter route "test"` once in a terminal (or do the global install from section 0), then restart the tool |
|
|
264
277
|
| 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) |
|
|
278
|
+
| Gemini CLI: "MCP servers are configured but disabled because this folder is untrusted" | Trust the folder (Gemini asks on start, or use `/permissions`) |
|
|
279
|
+
| Cursor: skill-router "not loaded (needs approval)" | Turn it on in **Cursor Settings → MCP**, or run `cursor-agent mcp enable skill-router` |
|
|
265
280
|
| 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 |
|
|
266
281
|
| 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 |
|
|
267
282
|
|
|
@@ -271,12 +286,13 @@ Add these to the `args` of an MCP setup, or to `skill-router` on the command lin
|
|
|
271
286
|
|
|
272
287
|
| Platform | Status |
|
|
273
288
|
|---|---|
|
|
274
|
-
| Claude Code, terminal and plugin | ✅ Installed from the npm package's marketplace folder (fresh, isolated config)
|
|
289
|
+
| Claude Code, terminal and plugin | ✅ Installed from the npm package's marketplace folder (fresh, isolated config). In real sessions, Claude loaded the right skill before editing in 16/16 runs (0.1.4), followed named skills, and stayed quiet on chit-chat. The MCP-only setup from section 2 also passed |
|
|
275
290
|
| 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 |
|
|
276
291
|
| MCP server (all MCP clients) | ✅ Protocol tested: `tools/list`, `route_skill`, `get_skill` |
|
|
277
292
|
| Claude Desktop `.mcpb` | ⚠️ Bundle validated and its server tested; install through Settings not yet tried |
|
|
278
|
-
|
|
|
293
|
+
| Codex CLI 0.164, Gemini CLI 0.66, Cursor agent CLI | ✅ Config from this guide read as written and server connected (tools listed). ⚠️ A model choosing the tools on its own not yet observed (the test machine wasn't logged in to these tools) |
|
|
294
|
+
| GitHub Copilot, Windsurf | ⚠️ Written to each tool's documented format; not yet run |
|
|
279
295
|
| Windows | ⚠️ Not tested |
|
|
280
|
-
| Router skill copied from the package (section 9) |
|
|
296
|
+
| Router skill copied from the package (section 9) | ✅ Tested in Claude Code (project `.claude/skills`): it routes through the CLI and names a fitting skill |
|
|
281
297
|
|
|
282
298
|
Found a problem or a step that didn't match? Tell the person who shared this guide with you.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@originkit/skillrouter",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
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": {
|
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
"test": "node --test test/*.test.ts",
|
|
9
9
|
"eval": "node test/eval.ts",
|
|
10
10
|
"prepublishOnly": "npm run build",
|
|
11
|
-
"build:mcpb": "bash mcpb/build.sh"
|
|
11
|
+
"build:mcpb": "bash mcpb/build.sh",
|
|
12
|
+
"release-check": "node test/release-check.mjs"
|
|
12
13
|
},
|
|
13
14
|
"license": "MIT",
|
|
14
15
|
"type": "module",
|
|
@@ -40,7 +41,8 @@
|
|
|
40
41
|
"docs/setup.md",
|
|
41
42
|
".claude-plugin/marketplace.json",
|
|
42
43
|
"plugin/.claude-plugin/plugin.json",
|
|
43
|
-
"skills/skill-router/SKILL.md"
|
|
44
|
+
"skills/skill-router/SKILL.md",
|
|
45
|
+
"CHANGELOG.md"
|
|
44
46
|
],
|
|
45
47
|
"engines": {
|
|
46
48
|
"node": ">=22.18"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "skill-router",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"description": "Picks the right skill for each prompt from a large catalog (or your own skills) and loads only that one. No installing 200 skills.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "landerdevelopers"
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"hooks": [
|
|
19
19
|
{
|
|
20
20
|
"type": "command",
|
|
21
|
-
"command": "command -v skill-router >/dev/null 2>&1 && exec skill-router hook || exec npx --prefer-offline -y @originkit/skillrouter hook",
|
|
21
|
+
"command": "command -v skill-router >/dev/null 2>&1 && exec skill-router hook || exec npx --prefer-offline -y @originkit/skillrouter@0.1.4 hook",
|
|
22
22
|
"timeout": 15
|
|
23
23
|
}
|
|
24
24
|
]
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"args": [
|
|
32
32
|
"--prefer-offline",
|
|
33
33
|
"-y",
|
|
34
|
-
"@originkit/skillrouter",
|
|
34
|
+
"@originkit/skillrouter@0.1.4",
|
|
35
35
|
"mcp"
|
|
36
36
|
]
|
|
37
37
|
}
|