@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.
- package/README.md +106 -2
- package/data/keywords.json +6725 -0
- package/data/skills.json +4167 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +123 -0
- package/dist/index.d.ts +62 -0
- package/dist/index.js +343 -0
- package/dist/mcp.d.ts +6 -0
- package/dist/mcp.js +56 -0
- package/dist/types.d.ts +50 -0
- package/dist/types.js +1 -0
- package/docs/integrate.md +234 -0
- package/docs/setup.md +278 -0
- package/package.json +51 -4
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { text } from "node:stream/consumers";
|
|
5
|
+
import { parseArgs } from "node:util";
|
|
6
|
+
import { createRouter, discoverSkills, loadPack, loadSkillsDir, loadSkillBody } from "./index.js";
|
|
7
|
+
const USAGE = `skill-router — pick the right agent skill for a task
|
|
8
|
+
|
|
9
|
+
skill-router route "<task>" rank skills for a task
|
|
10
|
+
skill-router list list every loaded skill
|
|
11
|
+
skill-router show <id> print a skill's SKILL.md (fetched once, then cached)
|
|
12
|
+
skill-router mcp run as an MCP server on stdio
|
|
13
|
+
skill-router hook Claude Code UserPromptSubmit hook (prompt JSON on stdin)
|
|
14
|
+
|
|
15
|
+
--skills <dir> add a folder of SKILL.md skills (repeatable)
|
|
16
|
+
--no-pack don't load the bundled web-design pack
|
|
17
|
+
--no-discover don't look for installed skills (~/.claude/skills, ~/.agents/skills,
|
|
18
|
+
~/.codex/skills, ~/.cursor/skills and the same under the project)
|
|
19
|
+
-k <n> max skills returned (default 3)
|
|
20
|
+
--json machine-readable output`;
|
|
21
|
+
const { values, positionals } = parseArgs({
|
|
22
|
+
allowPositionals: true,
|
|
23
|
+
options: {
|
|
24
|
+
skills: { type: "string", multiple: true },
|
|
25
|
+
"no-pack": { type: "boolean" },
|
|
26
|
+
"no-discover": { type: "boolean" },
|
|
27
|
+
k: { type: "string", short: "k" },
|
|
28
|
+
json: { type: "boolean" },
|
|
29
|
+
help: { type: "boolean", short: "h" },
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
// Catalog first, installed skills after: an installed copy overrides its catalog entry.
|
|
33
|
+
// Read fresh on every call, so a skill installed a minute ago is already routable.
|
|
34
|
+
const loadAll = () => [
|
|
35
|
+
...(values["no-pack"] ? [] : loadPack()),
|
|
36
|
+
...(values["no-discover"] ? [] : discoverSkills()),
|
|
37
|
+
...(values.skills ?? []).flatMap((d) => loadSkillsDir(d)),
|
|
38
|
+
];
|
|
39
|
+
const [cmd, ...rest] = positionals;
|
|
40
|
+
if (!cmd || values.help) {
|
|
41
|
+
console.log(USAGE);
|
|
42
|
+
process.exit(cmd || values.help ? 0 : 1);
|
|
43
|
+
}
|
|
44
|
+
const CACHE = join(homedir(), ".cache", "skill-router");
|
|
45
|
+
// Below this RouteResult.confidence the hook stays silent.
|
|
46
|
+
const HOOK_MIN = 0.15;
|
|
47
|
+
if (cmd === "mcp") {
|
|
48
|
+
const { serve } = await import("./mcp.js");
|
|
49
|
+
await serve(loadAll, CACHE);
|
|
50
|
+
}
|
|
51
|
+
else if (cmd === "hook") {
|
|
52
|
+
// Claude Code UserPromptSubmit hook: route the prompt, add matches as context.
|
|
53
|
+
// Never blocks the prompt: any failure means no context, not an error.
|
|
54
|
+
try {
|
|
55
|
+
const { prompt } = JSON.parse(await text(process.stdin));
|
|
56
|
+
// Recall over precision: a list Claude doesn't need costs ~300 tokens and gets ignored (0 false loads on
|
|
57
|
+
// 9 off-topic prompts in bench/), while a missing skill is a miss. 8 lines at confidence >= 0.15 listed
|
|
58
|
+
// the right skill for 89% of blind tasks (was 77% at 5 lines, 0.25).
|
|
59
|
+
const res = prompt ? await createRouter(loadAll()).route(prompt, { k: values.k ? Number(values.k) : 8, relative: 0, minCoverage: 0.1 }) : null;
|
|
60
|
+
// Unsolicited, so stricter than route_skill: weak matches stay silent.
|
|
61
|
+
if (res && !res.none && res.confidence >= HOOK_MIN) {
|
|
62
|
+
const parts = [];
|
|
63
|
+
const how = (s) => (s.path ? `use the installed ${s.name} skill` : `load it with the get_skill tool, id "${s.id}"`);
|
|
64
|
+
const caution = (s) => (s.warnings?.length ? ` Caution: ${s.warnings.join("; ")}; tell the user before relying on it.` : "");
|
|
65
|
+
// Named by the user: load the instructions now instead of suggesting them.
|
|
66
|
+
for (const { skill: s } of res.matches.filter((m) => m.mentioned)) {
|
|
67
|
+
const body = await loadSkillBody(s, { cacheDir: CACHE }).catch(() => null);
|
|
68
|
+
const files = s.path
|
|
69
|
+
? `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>".`;
|
|
71
|
+
parts.push(body
|
|
72
|
+
? `skill-router: the user asked for the ${s.name} skill (${s.id}). Follow these instructions for this request. ${files}${caution(s)}\n<skill id="${s.id}">\n${clip(body, 30_000)}\n</skill>`
|
|
73
|
+
: `skill-router: the user asked for the ${s.name} skill (${s.id}); ${how(s)}.${caution(s)}`);
|
|
74
|
+
}
|
|
75
|
+
// Otherwise a short list for Claude to judge. Word matching alone is right first only about half the time on
|
|
76
|
+
// unseen prompts, but a model picking from its list gets ~3 in 4 (data/eval-holdout.json), so ask Claude to
|
|
77
|
+
// check actively: a bare "may fit" was skipped even when right, in live runs.
|
|
78
|
+
const suggested = res.matches.filter((m) => !m.mentioned);
|
|
79
|
+
if (suggested.length && !parts.length) {
|
|
80
|
+
// 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
|
+
const lines = suggested.map(({ skill: s }) => {
|
|
82
|
+
const about = (s.summary ?? s.description).replace(/\s+/g, " ").slice(0, 160);
|
|
83
|
+
return `- ${s.id}: ${about}${s.path ? " [installed]" : ""}${caution(s)}`;
|
|
84
|
+
});
|
|
85
|
+
parts.push(`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) and load it: an installed one by using the skill, any other with the get_skill tool (id = its id below). Then follow it. Skip this only if none of them is about this task.\n${lines.join("\n")}`);
|
|
86
|
+
}
|
|
87
|
+
const additionalContext = parts.join("\n\n");
|
|
88
|
+
console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext } }));
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
catch { }
|
|
92
|
+
}
|
|
93
|
+
else {
|
|
94
|
+
const router = createRouter(loadAll());
|
|
95
|
+
const out = (data, text) => console.log(values.json ? JSON.stringify(data, null, 2) : text);
|
|
96
|
+
if (cmd === "route") {
|
|
97
|
+
const task = rest.join(" ");
|
|
98
|
+
if (!task)
|
|
99
|
+
throw new Error('route needs a task: skill-router route "make our hero look distinctive"');
|
|
100
|
+
const res = await router.route(task, { k: values.k ? Number(values.k) : undefined });
|
|
101
|
+
out(res, res.none
|
|
102
|
+
? "No skill fits this task."
|
|
103
|
+
: res.matches
|
|
104
|
+
.map((m) => `${m.score.toFixed(2)} ${m.skill.id}${m.mentioned ? " (named)" : ""}${m.skill.path ? " (installed)" : ""}${m.skill.warnings?.length ? ` ⚠ ${m.skill.warnings.join("; ")}` : ""}\n ${m.skill.summary ?? m.skill.description.slice(0, 120)}`)
|
|
105
|
+
.join("\n"));
|
|
106
|
+
}
|
|
107
|
+
else if (cmd === "list") {
|
|
108
|
+
out(router.skills, router.skills.map((s) => s.id).join("\n"));
|
|
109
|
+
}
|
|
110
|
+
else if (cmd === "show") {
|
|
111
|
+
const s = router.get(rest[0] ?? "");
|
|
112
|
+
if (!s)
|
|
113
|
+
throw new Error(`no skill with id ${rest[0]}`);
|
|
114
|
+
console.log((await loadSkillBody(s, { cacheDir: CACHE })) ?? JSON.stringify(s, null, 2));
|
|
115
|
+
}
|
|
116
|
+
else {
|
|
117
|
+
console.error(USAGE);
|
|
118
|
+
process.exit(1);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
function clip(s, n) {
|
|
122
|
+
return s.length > n ? `${s.slice(0, n)}\n[truncated: read the rest with the get_skill tool]` : s;
|
|
123
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { Complete, Match, RouteResult, Skill } from "./types.ts";
|
|
2
|
+
export type * from "./types.ts";
|
|
3
|
+
/** The bundled web-design pack (data/skills.json). */
|
|
4
|
+
export declare const PACK_PATH: string;
|
|
5
|
+
export declare function loadPack(path?: string): Skill[];
|
|
6
|
+
/** Parse a SKILL.md file. Returns null when it has no usable frontmatter. */
|
|
7
|
+
export declare function parseSkillFile(path: string, id?: string): Skill | null;
|
|
8
|
+
/** Find every SKILL.md under `dir` (skills nest at most a few levels deep). */
|
|
9
|
+
export declare function loadSkillsDir(dir: string, maxDepth?: number): Skill[];
|
|
10
|
+
/** Where agents keep installed skills: user-wide first, then the project's (which win on clashes). */
|
|
11
|
+
export declare function skillDirs(cwd?: string): string[];
|
|
12
|
+
/** The skills this user already has installed, from the usual agent folders. */
|
|
13
|
+
export declare function discoverSkills(cwd?: string): Skill[];
|
|
14
|
+
export interface RouteOptions {
|
|
15
|
+
/** Max skills returned. Default 3. */
|
|
16
|
+
k?: number;
|
|
17
|
+
/** Lexical: absolute BM25 floor for the top hit. Default 0 (off): BM25 scale shifts with catalog size. */
|
|
18
|
+
minScore?: number;
|
|
19
|
+
/** Lexical: rarity-weighted share of the task's words the top hit must match. Default DEFAULT_MIN_COVERAGE. */
|
|
20
|
+
minCoverage?: number;
|
|
21
|
+
/** Lexical: keep hits scoring at least this fraction of the top hit. Default 0.5. */
|
|
22
|
+
relative?: number;
|
|
23
|
+
/** When given, a model picks from the top `candidates` lexical hits. */
|
|
24
|
+
complete?: Complete;
|
|
25
|
+
/** How many lexical hits the model sees. Default 40: the right skill can rank low lexically when the task names its page ("pricing page", "landing page") more than its problem. */
|
|
26
|
+
candidates?: number;
|
|
27
|
+
}
|
|
28
|
+
export interface Router {
|
|
29
|
+
skills: Skill[];
|
|
30
|
+
get(id: string): Skill | undefined;
|
|
31
|
+
/** Lexical candidates only, best first, unfiltered. */
|
|
32
|
+
search(task: string, limit?: number): Match[];
|
|
33
|
+
route(task: string, opts?: RouteOptions): Promise<RouteResult>;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Lexical: the top hit must match at least this share of the task's words, each word weighted
|
|
37
|
+
* by how rare it is across the skills (rare words carry the intent). Calibrated on data/eval.json
|
|
38
|
+
* with `node test/eval.ts --sweep`. Relative, so it holds from 2 skills to 2,000.
|
|
39
|
+
*/
|
|
40
|
+
export declare const DEFAULT_MIN_COVERAGE = 0.25;
|
|
41
|
+
export interface RouterOptions {
|
|
42
|
+
/**
|
|
43
|
+
* Weight of problem keywords ("cramped", "janky") against the description (1). Default 2: on the
|
|
44
|
+
* blind holdout it took the right skill from 83% to 98% inside the top 40, and 14% to 38% first on symptom-only tasks.
|
|
45
|
+
*/
|
|
46
|
+
keywordBoost?: number;
|
|
47
|
+
}
|
|
48
|
+
export declare function createRouter(skills: Skill[], { keywordBoost }?: RouterOptions): Router;
|
|
49
|
+
export declare function rerankPrompt(task: string, hits: Match[], k: number): string;
|
|
50
|
+
export interface BodyOptions {
|
|
51
|
+
/** A file next to SKILL.md, e.g. "references/rules.md". Default "SKILL.md". */
|
|
52
|
+
file?: string;
|
|
53
|
+
/** Where fetched files are kept. Without it they're cached in memory only. */
|
|
54
|
+
cacheDir?: string;
|
|
55
|
+
fetch?: typeof fetch;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* A skill's instructions (or a file beside them), loaded only when the skill is picked:
|
|
59
|
+
* from disk for local skills, else from its commit-pinned `source`, fetched once and cached.
|
|
60
|
+
* Pinned to a commit, the content never changes, so the cache never goes stale.
|
|
61
|
+
*/
|
|
62
|
+
export declare function loadSkillBody(skill: Skill, opts?: BodyOptions): Promise<string | null>;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { readFileSync, readdirSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
|
|
3
|
+
import { homedir } from "node:os";
|
|
4
|
+
import { join, relative, dirname, resolve, sep } from "node:path";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
import MiniSearch from "minisearch";
|
|
7
|
+
import { parse as parseYaml } from "yaml";
|
|
8
|
+
/** The bundled web-design pack (data/skills.json). */
|
|
9
|
+
export const PACK_PATH = fileURLToPath(new URL("../data/skills.json", import.meta.url));
|
|
10
|
+
export function loadPack(path = PACK_PATH) {
|
|
11
|
+
// Problem keywords (data/keywords.json beside the pack) are optional: index them when present.
|
|
12
|
+
const kwPath = join(dirname(path), "keywords.json");
|
|
13
|
+
const keywords = existsSync(kwPath) ? JSON.parse(readFileSync(kwPath, "utf8")) : {};
|
|
14
|
+
// A catalog describes skills; where one is installed is this machine's business (discoverSkills).
|
|
15
|
+
return JSON.parse(readFileSync(path, "utf8")).map(({ path: _, ...s }) => keywords[s.id] && !s.keywords ? { ...s, keywords: keywords[s.id] } : s);
|
|
16
|
+
}
|
|
17
|
+
/** Parse a SKILL.md file. Returns null when it has no usable frontmatter. */
|
|
18
|
+
export function parseSkillFile(path, id) {
|
|
19
|
+
const text = readFileSync(path, "utf8");
|
|
20
|
+
const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
|
|
21
|
+
if (!m)
|
|
22
|
+
return null;
|
|
23
|
+
let fm;
|
|
24
|
+
try {
|
|
25
|
+
fm = parseYaml(m[1]) ?? {};
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
// Real SKILL.md files often hold invalid YAML ("description: Triggers on: x, y").
|
|
29
|
+
// Harnesses accept them, so do too: one `key: rest of line` per line.
|
|
30
|
+
fm = Object.fromEntries(m[1].split(/\r?\n/).flatMap((l) => {
|
|
31
|
+
const kv = /^([\w-]+):\s*(.*)$/.exec(l);
|
|
32
|
+
return kv ? [[kv[1], kv[2].replace(/^(["'])(.*)\1$/, "$2")]] : [];
|
|
33
|
+
}));
|
|
34
|
+
}
|
|
35
|
+
const name = typeof fm.name === "string" ? fm.name : dirname(path).split(/[\\/]/).pop();
|
|
36
|
+
const description = typeof fm.description === "string" ? fm.description.trim() : "";
|
|
37
|
+
if (!description)
|
|
38
|
+
return null;
|
|
39
|
+
return { id: id ?? `local/${name}`, name, description, path };
|
|
40
|
+
}
|
|
41
|
+
/** Find every SKILL.md under `dir` (skills nest at most a few levels deep). */
|
|
42
|
+
export function loadSkillsDir(dir, maxDepth = 4) {
|
|
43
|
+
const out = [];
|
|
44
|
+
const seen = new Set();
|
|
45
|
+
const walk = (d, depth) => {
|
|
46
|
+
let entries;
|
|
47
|
+
try {
|
|
48
|
+
// Sorted so ids are stable across filesystems.
|
|
49
|
+
entries = readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
return;
|
|
53
|
+
}
|
|
54
|
+
for (const e of entries) {
|
|
55
|
+
if (e.name === "node_modules" || e.name.startsWith("."))
|
|
56
|
+
continue;
|
|
57
|
+
const p = join(d, e.name);
|
|
58
|
+
if (e.isDirectory() && depth < maxDepth)
|
|
59
|
+
walk(p, depth + 1);
|
|
60
|
+
else if (e.name === "SKILL.md") {
|
|
61
|
+
const s = parseSkillFile(p);
|
|
62
|
+
if (!s)
|
|
63
|
+
continue;
|
|
64
|
+
// Same name twice in one tree: disambiguate by folder.
|
|
65
|
+
if (seen.has(s.id))
|
|
66
|
+
s.id = `local/${relative(dir, dirname(p))}`;
|
|
67
|
+
seen.add(s.id);
|
|
68
|
+
out.push(s);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
};
|
|
72
|
+
walk(dir, 0);
|
|
73
|
+
return out;
|
|
74
|
+
}
|
|
75
|
+
/** Where agents keep installed skills: user-wide first, then the project's (which win on clashes). */
|
|
76
|
+
export function skillDirs(cwd = process.cwd()) {
|
|
77
|
+
const roots = [".claude", ".agents", ".codex", ".cursor"];
|
|
78
|
+
return [...new Set([...roots.map((r) => join(homedir(), r, "skills")), ...roots.map((r) => join(cwd, r, "skills"))])];
|
|
79
|
+
}
|
|
80
|
+
/** The skills this user already has installed, from the usual agent folders. */
|
|
81
|
+
export function discoverSkills(cwd) {
|
|
82
|
+
return skillDirs(cwd).flatMap((d) => loadSkillsDir(d));
|
|
83
|
+
}
|
|
84
|
+
// Main picks get a nudge, "use with care" a penalty: a prior, not a filter.
|
|
85
|
+
const TIER_WEIGHT = { main: 1.15, good: 1, care: 0.8 };
|
|
86
|
+
// The user installed it: a stronger signal than any curated tier.
|
|
87
|
+
const INSTALLED_WEIGHT = 1.2;
|
|
88
|
+
function prior(s) {
|
|
89
|
+
const tiers = s.placements?.map((p) => p.tier) ?? [];
|
|
90
|
+
const tier = tiers.length ? Math.max(...tiers.map((t) => TIER_WEIGHT[t])) : s.warnings?.length ? TIER_WEIGHT.care : 1;
|
|
91
|
+
return tier * (s.path ? INSTALLED_WEIGHT : 1);
|
|
92
|
+
}
|
|
93
|
+
// Words that say nothing about which skill to pick.
|
|
94
|
+
const STOP = new Set("a an the and or but of to in on for with my our your their this that these those is are be it its i we you me us can could would should please make want need help me do does how what why using use into from at as by about some any just yes no ok okay thanks thank cool great sure go ahead continue now then also again done lets let when where which who they them there here re ll ve don doesn isn didn won did does get got set up out will has have had was were been not all so if than very really actually look looks good nice fine ship change changed thing things stuff something".split(" "));
|
|
95
|
+
/**
|
|
96
|
+
* Lexical: the top hit must match at least this share of the task's words, each word weighted
|
|
97
|
+
* by how rare it is across the skills (rare words carry the intent). Calibrated on data/eval.json
|
|
98
|
+
* with `node test/eval.ts --sweep`. Relative, so it holds from 2 skills to 2,000.
|
|
99
|
+
*/
|
|
100
|
+
export const DEFAULT_MIN_COVERAGE = 0.25;
|
|
101
|
+
const tokenize = (s) => s.split(/[^\p{L}\p{N}]+/u);
|
|
102
|
+
const processTerm = (t) => {
|
|
103
|
+
const w = t.toLowerCase();
|
|
104
|
+
return STOP.has(w) || w.length < 2 ? null : w;
|
|
105
|
+
};
|
|
106
|
+
export function createRouter(skills, { keywordBoost = 2 } = {}) {
|
|
107
|
+
// Same id twice: merge, later fields win (an installed copy keeps the catalog's categories).
|
|
108
|
+
const byId = new Map();
|
|
109
|
+
for (const s of skills)
|
|
110
|
+
byId.set(s.id, { ...byId.get(s.id), ...s });
|
|
111
|
+
// An installed skill that is also in the catalog is one skill: the catalog's id and metadata,
|
|
112
|
+
// the installed copy's instructions. Only when the name points at one entry (names collide).
|
|
113
|
+
const aliases = new Map();
|
|
114
|
+
const catalog = new Map();
|
|
115
|
+
for (const s of byId.values())
|
|
116
|
+
if (!s.path)
|
|
117
|
+
catalog.set(s.name, [...(catalog.get(s.name) ?? []), s]);
|
|
118
|
+
for (const [id, s] of byId) {
|
|
119
|
+
if (!s.path)
|
|
120
|
+
continue;
|
|
121
|
+
const same = catalog.get(s.name) ?? [];
|
|
122
|
+
const twin = same.length === 1 ? same[0] : same.find((c) => c.description === s.description);
|
|
123
|
+
if (!twin)
|
|
124
|
+
continue;
|
|
125
|
+
byId.set(twin.id, { ...twin, description: s.description, path: s.path });
|
|
126
|
+
byId.delete(id);
|
|
127
|
+
aliases.set(id, twin.id);
|
|
128
|
+
}
|
|
129
|
+
// A skill renamed upstream resolves to its successor, which inherits its catalog placements.
|
|
130
|
+
for (const [id, s] of byId) {
|
|
131
|
+
const next = s.replacedBy ? byId.get(s.replacedBy) : undefined;
|
|
132
|
+
if (!next)
|
|
133
|
+
continue;
|
|
134
|
+
const placements = [...(next.placements ?? []), ...(s.placements ?? [])];
|
|
135
|
+
// The old entry's summary describes the skill; the successor's may only point back at it ("…under its newer name").
|
|
136
|
+
byId.set(next.id, { ...next, summary: s.summary ?? next.summary, placements: placements.filter((p, i) => placements.findIndex((q) => q.category === p.category) === i) });
|
|
137
|
+
byId.delete(id);
|
|
138
|
+
aliases.set(id, next.id);
|
|
139
|
+
}
|
|
140
|
+
// The same skill synced into several folders is one skill.
|
|
141
|
+
const seen = new Set();
|
|
142
|
+
for (const [id, s] of byId) {
|
|
143
|
+
const key = `${s.name}\0${s.description}`;
|
|
144
|
+
if (seen.has(key))
|
|
145
|
+
byId.delete(id);
|
|
146
|
+
seen.add(key);
|
|
147
|
+
}
|
|
148
|
+
const all = [...byId.values()];
|
|
149
|
+
const get = (id) => byId.get(id) ?? byId.get(aliases.get(id) ?? "");
|
|
150
|
+
const index = new MiniSearch({
|
|
151
|
+
fields: ["name", "summary", "description", "categories", "keywords"],
|
|
152
|
+
idField: "id",
|
|
153
|
+
processTerm,
|
|
154
|
+
tokenize,
|
|
155
|
+
searchOptions: {
|
|
156
|
+
boost: { name: 3, summary: 1.5, categories: 1.2, description: 1, keywords: keywordBoost },
|
|
157
|
+
prefix: (t) => t.length > 3,
|
|
158
|
+
fuzzy: (t) => (t.length > 5 ? 0.15 : false),
|
|
159
|
+
combineWith: "OR",
|
|
160
|
+
},
|
|
161
|
+
});
|
|
162
|
+
const docs = all.map((s) => ({
|
|
163
|
+
...s,
|
|
164
|
+
summary: s.summary ?? "",
|
|
165
|
+
name: s.name.replace(/-/g, " "),
|
|
166
|
+
categories: (s.placements ?? []).map((p) => p.category.replace(/-/g, " ")).join(" "),
|
|
167
|
+
keywords: (s.keywords ?? []).join(" "),
|
|
168
|
+
}));
|
|
169
|
+
index.addAll(docs);
|
|
170
|
+
// Document frequency per term, for weighting the task's words by rarity.
|
|
171
|
+
const df = new Map();
|
|
172
|
+
for (const doc of docs) {
|
|
173
|
+
const terms = new Set(tokenize([doc.name, doc.summary, doc.description, doc.categories, doc.keywords].join(" ")).map(processTerm));
|
|
174
|
+
for (const t of terms)
|
|
175
|
+
if (t)
|
|
176
|
+
df.set(t, (df.get(t) ?? 0) + 1);
|
|
177
|
+
}
|
|
178
|
+
// A word no skill uses weighs like the rarest one: it says the task may be about something else.
|
|
179
|
+
const weight = (t) => Math.log(1 + all.length / (df.get(t) ?? 1));
|
|
180
|
+
const rank = (task, limit) => index
|
|
181
|
+
.search(task)
|
|
182
|
+
.map((r) => ({
|
|
183
|
+
skill: byId.get(r.id),
|
|
184
|
+
score: r.score * prior(byId.get(r.id)),
|
|
185
|
+
matched: new Set(r.queryTerms),
|
|
186
|
+
}))
|
|
187
|
+
.sort((a, b) => b.score - a.score)
|
|
188
|
+
.slice(0, limit);
|
|
189
|
+
const search = (task, limit = 50) => rank(task, limit).map(({ skill, score }) => ({ skill, score }));
|
|
190
|
+
// Skills the task asks for by name: "/frontend-design", "$seo-audit", "break-ui", "the seo skill",
|
|
191
|
+
// or a full id. Single-word names need "skill" after them: "animate the cards" names nothing.
|
|
192
|
+
function named(task, hits) {
|
|
193
|
+
const t = task.toLowerCase();
|
|
194
|
+
const groups = new Map();
|
|
195
|
+
for (const s of all) {
|
|
196
|
+
const n = s.name.toLowerCase();
|
|
197
|
+
const e = n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
198
|
+
const hit = t.includes(s.id.toLowerCase()) ||
|
|
199
|
+
new RegExp(`(?<![\\w-])[/$]${e}(?![\\w-])`).test(t) ||
|
|
200
|
+
(n.includes("-") && new RegExp(`(?<![\\w-])${e}(?![\\w-])`).test(t)) ||
|
|
201
|
+
new RegExp(`(?<![\\w-])${e}\\s+skill\\b`).test(t);
|
|
202
|
+
if (hit)
|
|
203
|
+
groups.set(n, [...(groups.get(n) ?? []), s]);
|
|
204
|
+
}
|
|
205
|
+
// Several skills share the name: the one whose owner the task mentions, else installed, else best ranked.
|
|
206
|
+
const pos = (s) => {
|
|
207
|
+
const i = hits.findIndex((h) => h.skill === s);
|
|
208
|
+
return i < 0 ? Infinity : i;
|
|
209
|
+
};
|
|
210
|
+
return [...groups.values()].map((g) => g.find((s) => s.repo && t.includes(s.repo.split("/")[0].toLowerCase())) ??
|
|
211
|
+
g.find((s) => s.path) ??
|
|
212
|
+
[...g].sort((a, b) => pos(a) - pos(b) || prior(b) - prior(a))[0]);
|
|
213
|
+
}
|
|
214
|
+
async function route(task, opts = {}) {
|
|
215
|
+
const { k = 3, minScore = 0, minCoverage = DEFAULT_MIN_COVERAGE, relative = 0.5, complete, candidates = 40, } = opts;
|
|
216
|
+
// Small catalogs: let the model see everything, lexical overlap or not.
|
|
217
|
+
// Enough hits for both the rerank pool and the k results asked for.
|
|
218
|
+
const hits = rank(task, Math.max(candidates, k));
|
|
219
|
+
// Named skills always come first and skip the no-fit check: the user chose them.
|
|
220
|
+
const pinned = named(task, hits).map((skill) => ({ skill, score: 1, reason: "named in the task", mentioned: true }));
|
|
221
|
+
const withPinned = (rest, via, confidence = 0) => {
|
|
222
|
+
const matches = [...pinned, ...rest.filter((m) => !pinned.some((p) => p.skill === m.skill))].slice(0, Math.max(k, pinned.length));
|
|
223
|
+
return { matches, none: matches.length === 0, via, confidence: pinned.length ? 1 : +confidence.toFixed(3) };
|
|
224
|
+
};
|
|
225
|
+
if (complete) {
|
|
226
|
+
const pool = all.length <= candidates ? all.map((skill) => ({ skill, score: 0 })) : hits;
|
|
227
|
+
const picked = pool.length ? await rerank(task, pool, complete, k) : [];
|
|
228
|
+
if (picked)
|
|
229
|
+
return withPinned(picked, "llm", Math.max(0, ...picked.map((m) => m.score)));
|
|
230
|
+
// Unparseable model output: fall through to lexical rather than fail.
|
|
231
|
+
}
|
|
232
|
+
const top = hits[0]?.score ?? 0;
|
|
233
|
+
// One shared generic word ("write", "page") is not a match when the task says more.
|
|
234
|
+
const words = [...new Set(tokenize(task).map(processTerm))].filter((t) => !!t);
|
|
235
|
+
const total = words.reduce((sum, t) => sum + weight(t), 0);
|
|
236
|
+
// Covered by the leading hits together: "font pairing for a landing page" spans two skills.
|
|
237
|
+
const lead = new Set(hits.slice(0, 3).flatMap((h) => [...h.matched]));
|
|
238
|
+
const got = words.filter((t) => lead.has(t)).reduce((sum, t) => sum + weight(t), 0);
|
|
239
|
+
if (!hits.length || !total || top < minScore || got / total < minCoverage)
|
|
240
|
+
return withPinned([], "lexical");
|
|
241
|
+
// How much of the task the best skill covers on its own: one skill that owns the task is a strong match.
|
|
242
|
+
const own = words.filter((t) => hits[0].matched.has(t)).reduce((sum, t) => sum + weight(t), 0) / total;
|
|
243
|
+
const matches = hits
|
|
244
|
+
.filter((h) => h.score >= top * relative)
|
|
245
|
+
.slice(0, k)
|
|
246
|
+
.map((h) => ({ skill: h.skill, score: +(h.score / top).toFixed(3) }));
|
|
247
|
+
return withPinned(matches, "lexical", own);
|
|
248
|
+
}
|
|
249
|
+
return { skills: all, get, search, route };
|
|
250
|
+
}
|
|
251
|
+
export function rerankPrompt(task, hits, k) {
|
|
252
|
+
const list = hits
|
|
253
|
+
.map((h) => {
|
|
254
|
+
const s = h.skill;
|
|
255
|
+
const warn = s.warnings?.length ? `\n caution: ${s.warnings.join("; ")}` : "";
|
|
256
|
+
return `- id: ${s.id}\n ${clip(s.description, 500)}${s.summary ? `\n summary: ${s.summary}` : ""}${warn}`;
|
|
257
|
+
})
|
|
258
|
+
.join("\n");
|
|
259
|
+
return `You route a task to the agent skills that should be loaded for it.
|
|
260
|
+
|
|
261
|
+
Task:
|
|
262
|
+
<task>
|
|
263
|
+
${task}
|
|
264
|
+
</task>
|
|
265
|
+
|
|
266
|
+
Candidate skills:
|
|
267
|
+
${list}
|
|
268
|
+
|
|
269
|
+
Pick at most ${k} skills that directly help with this task, best first. Pick several only when the task genuinely needs each one (e.g. copy AND visual design). Prefer skills without cautions when two fit equally. If none clearly fits, pick none: a wrong skill is worse than no skill.
|
|
270
|
+
|
|
271
|
+
Reply with JSON only: {"picks":[{"id":"<id>","confidence":0.0-1.0,"reason":"<one short clause>"}]}`;
|
|
272
|
+
}
|
|
273
|
+
async function rerank(task, hits, complete, k) {
|
|
274
|
+
let parsed;
|
|
275
|
+
try {
|
|
276
|
+
const raw = await complete(rerankPrompt(task, hits, k));
|
|
277
|
+
parsed = JSON.parse(raw.slice(raw.indexOf("{"), raw.lastIndexOf("}") + 1));
|
|
278
|
+
}
|
|
279
|
+
catch {
|
|
280
|
+
return null;
|
|
281
|
+
}
|
|
282
|
+
if (!Array.isArray(parsed.picks))
|
|
283
|
+
return null;
|
|
284
|
+
const byId = new Map(hits.map((h) => [h.skill.id, h.skill]));
|
|
285
|
+
const out = [];
|
|
286
|
+
for (const p of parsed.picks) {
|
|
287
|
+
const skill = typeof p.id === "string" ? byId.get(p.id) : undefined;
|
|
288
|
+
if (!skill || out.some((m) => m.skill === skill))
|
|
289
|
+
continue; // ignore invented or repeated ids
|
|
290
|
+
const c = Number(p.confidence);
|
|
291
|
+
out.push({
|
|
292
|
+
skill,
|
|
293
|
+
score: Number.isFinite(c) ? Math.min(1, Math.max(0, c)) : 0.5,
|
|
294
|
+
reason: typeof p.reason === "string" ? p.reason : undefined,
|
|
295
|
+
});
|
|
296
|
+
}
|
|
297
|
+
return out.slice(0, k);
|
|
298
|
+
}
|
|
299
|
+
function clip(s, n) {
|
|
300
|
+
const t = s.replace(/\s+/g, " ").trim();
|
|
301
|
+
return t.length > n ? `${t.slice(0, n - 1)}…` : t;
|
|
302
|
+
}
|
|
303
|
+
const memo = new Map();
|
|
304
|
+
/**
|
|
305
|
+
* A skill's instructions (or a file beside them), loaded only when the skill is picked:
|
|
306
|
+
* from disk for local skills, else from its commit-pinned `source`, fetched once and cached.
|
|
307
|
+
* Pinned to a commit, the content never changes, so the cache never goes stale.
|
|
308
|
+
*/
|
|
309
|
+
export async function loadSkillBody(skill, opts = {}) {
|
|
310
|
+
const file = opts.file ?? "SKILL.md";
|
|
311
|
+
if (skill.path) {
|
|
312
|
+
const dir = dirname(skill.path);
|
|
313
|
+
const p = resolve(dir, file);
|
|
314
|
+
if (!p.startsWith(dir + sep))
|
|
315
|
+
throw new Error(`${file} is outside the skill`);
|
|
316
|
+
return existsSync(p) ? readFileSync(p, "utf8") : null;
|
|
317
|
+
}
|
|
318
|
+
if (!skill.source)
|
|
319
|
+
return null;
|
|
320
|
+
const dir = new URL(".", skill.source).href;
|
|
321
|
+
const url = new URL(file, skill.source).href;
|
|
322
|
+
if (!url.startsWith(dir))
|
|
323
|
+
throw new Error(`${file} is outside the skill`);
|
|
324
|
+
const hit = memo.get(url);
|
|
325
|
+
if (hit !== undefined)
|
|
326
|
+
return hit;
|
|
327
|
+
const cached = opts.cacheDir && join(opts.cacheDir, `${createHash("sha256").update(url).digest("hex")}.md`);
|
|
328
|
+
if (cached && existsSync(cached)) {
|
|
329
|
+
const text = readFileSync(cached, "utf8");
|
|
330
|
+
memo.set(url, text);
|
|
331
|
+
return text;
|
|
332
|
+
}
|
|
333
|
+
const res = await (opts.fetch ?? fetch)(url);
|
|
334
|
+
if (!res.ok)
|
|
335
|
+
return null;
|
|
336
|
+
const text = await res.text();
|
|
337
|
+
memo.set(url, text);
|
|
338
|
+
if (cached) {
|
|
339
|
+
mkdirSync(opts.cacheDir, { recursive: true });
|
|
340
|
+
writeFileSync(cached, text);
|
|
341
|
+
}
|
|
342
|
+
return text;
|
|
343
|
+
}
|
package/dist/mcp.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { Skill } from "./types.ts";
|
|
2
|
+
/**
|
|
3
|
+
* The calling agent is the reranker: route_skill hands it the lexical shortlist with
|
|
4
|
+
* descriptions, and the agent's own model picks. No API key needed on this side.
|
|
5
|
+
*/
|
|
6
|
+
export declare function serve(load: () => Skill[], cacheDir?: string): Promise<void>;
|
package/dist/mcp.js
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import { createRouter, loadSkillBody } from "./index.js";
|
|
5
|
+
const text = (t) => ({ content: [{ type: "text", text: t }] });
|
|
6
|
+
/**
|
|
7
|
+
* The calling agent is the reranker: route_skill hands it the lexical shortlist with
|
|
8
|
+
* descriptions, and the agent's own model picks. No API key needed on this side.
|
|
9
|
+
*/
|
|
10
|
+
export async function serve(load, cacheDir) {
|
|
11
|
+
// Rebuilt per call (tens of ms) so skills installed while the server runs are seen at once.
|
|
12
|
+
const router = () => createRouter(load());
|
|
13
|
+
const server = new McpServer({ name: "skill-router", version: "0.1.1" }, {
|
|
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
|
+
});
|
|
16
|
+
server.registerTool("route_skill", {
|
|
17
|
+
description: "Call before starting a task to find which agent skills apply. Returns up to 40 candidate skills, best lexical match first, one line each. Word matching ranks the page a task mentions (\"pricing page\") as highly as its problem (\"buttons feel flat\"), so read the whole list and judge: pick the skills that genuinely fit, or none. Then load a pick with get_skill.",
|
|
18
|
+
inputSchema: {
|
|
19
|
+
task: z.string().describe("The user's task, in their words plus any useful context"),
|
|
20
|
+
limit: z.number().int().min(1).max(60).optional().describe("Candidates to list, default 40"),
|
|
21
|
+
},
|
|
22
|
+
annotations: { readOnlyHint: true },
|
|
23
|
+
// Claude Code defers MCP tools behind a ToolSearch step; this loads them up front (saves a turn per skill load).
|
|
24
|
+
_meta: { "anthropic/alwaysLoad": true },
|
|
25
|
+
}, async ({ task, limit }) => {
|
|
26
|
+
// A long list of one-liners: the right skill can rank 30th lexically, and the agent is the better judge.
|
|
27
|
+
const res = await router().route(task, { k: limit ?? 40, relative: 0 });
|
|
28
|
+
if (res.none)
|
|
29
|
+
return text("No skill matches this task. Proceed without one.");
|
|
30
|
+
const lines = res.matches.map(({ skill: s, mentioned }, i) => {
|
|
31
|
+
const tags = [mentioned ? "named in the task" : i === 0 && res.confidence >= 0.5 ? "strong match" : "", s.path ? "installed" : "", s.warnings?.length ? `caution: ${s.warnings.join("; ")}` : ""].filter(Boolean);
|
|
32
|
+
const about = (s.summary ?? s.description).replace(/\s+/g, " ");
|
|
33
|
+
return `- ${s.id}: ${about.length > 200 ? `${about.slice(0, 199)}…` : about}${tags.length ? ` [${tags.join(", ")}]` : ""}`;
|
|
34
|
+
});
|
|
35
|
+
return text(`${lines.join("\n")}\n\nLoad a pick's full instructions with get_skill.`);
|
|
36
|
+
});
|
|
37
|
+
server.registerTool("get_skill", {
|
|
38
|
+
description: "Return a skill's instructions (its SKILL.md), or a file it references such as references/rules.md. Fetched once, then cached.",
|
|
39
|
+
inputSchema: {
|
|
40
|
+
id: z.string(),
|
|
41
|
+
file: z.string().optional().describe("A file the skill's instructions point to, relative to SKILL.md"),
|
|
42
|
+
},
|
|
43
|
+
annotations: { readOnlyHint: true },
|
|
44
|
+
// Claude Code defers MCP tools behind a ToolSearch step; this loads them up front (saves a turn per skill load).
|
|
45
|
+
_meta: { "anthropic/alwaysLoad": true },
|
|
46
|
+
}, async ({ id, file }) => {
|
|
47
|
+
const s = router().get(id);
|
|
48
|
+
if (!s)
|
|
49
|
+
return { ...text(`Unknown skill id: ${id}`), isError: true };
|
|
50
|
+
const body = await loadSkillBody(s, { file, cacheDir }).catch((e) => e);
|
|
51
|
+
if (body instanceof Error)
|
|
52
|
+
return { ...text(body.message), isError: true };
|
|
53
|
+
return text(body ?? (file ? `${id} has no ${file}.` : JSON.stringify(s, null, 2)));
|
|
54
|
+
});
|
|
55
|
+
await server.connect(new StdioServerTransport());
|
|
56
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/** One skill the router can choose. `id` is unique: `owner/repo/skill`, or `local/<skill>` for unpublished ones. */
|
|
2
|
+
export interface Skill {
|
|
3
|
+
id: string;
|
|
4
|
+
name: string;
|
|
5
|
+
/** The SKILL.md frontmatter description: what the skill does and when to use it. */
|
|
6
|
+
description: string;
|
|
7
|
+
repo?: string;
|
|
8
|
+
/** One-line human summary, e.g. from a curated list. Indexed alongside description. */
|
|
9
|
+
summary?: string;
|
|
10
|
+
/** Where the skill sits in a curated catalog. A skill can sit in several categories. */
|
|
11
|
+
placements?: Placement[];
|
|
12
|
+
/** Security/audit caveats. A skill with warnings is never picked silently. */
|
|
13
|
+
warnings?: string[];
|
|
14
|
+
install?: string;
|
|
15
|
+
/** Raw SKILL.md URL pinned to a commit, so the body can be fetched on demand and cached forever. */
|
|
16
|
+
source?: string;
|
|
17
|
+
/** Words users type when they need this skill ("cramped", "janky hover"). Indexed, never shown. */
|
|
18
|
+
keywords?: string[];
|
|
19
|
+
/** The id this skill was renamed to upstream; the router routes to that one instead. */
|
|
20
|
+
replacedBy?: string;
|
|
21
|
+
/** Path to SKILL.md when installed on this machine. */
|
|
22
|
+
path?: string;
|
|
23
|
+
}
|
|
24
|
+
export interface Placement {
|
|
25
|
+
category: string;
|
|
26
|
+
tier: Tier;
|
|
27
|
+
}
|
|
28
|
+
/** main = start here, good = solid alternative, care = check before use. */
|
|
29
|
+
export type Tier = "main" | "good" | "care";
|
|
30
|
+
export interface Match {
|
|
31
|
+
skill: Skill;
|
|
32
|
+
/** 0..1. Lexical score normalised to the top hit, or the model's confidence after rerank. */
|
|
33
|
+
score: number;
|
|
34
|
+
reason?: string;
|
|
35
|
+
/** The task named this skill ("use the break-ui skill"), so it was picked regardless of score. */
|
|
36
|
+
mentioned?: boolean;
|
|
37
|
+
}
|
|
38
|
+
export interface RouteResult {
|
|
39
|
+
matches: Match[];
|
|
40
|
+
/** True when nothing cleared the threshold: the router's honest "no skill fits". */
|
|
41
|
+
none: boolean;
|
|
42
|
+
via: "lexical" | "llm";
|
|
43
|
+
/**
|
|
44
|
+
* 0..1, how sure the top pick is. Lexical: rarity-weighted share of the task the best skill covers
|
|
45
|
+
* on its own. LLM: the model's top confidence. 1 when the task names a skill.
|
|
46
|
+
*/
|
|
47
|
+
confidence: number;
|
|
48
|
+
}
|
|
49
|
+
/** Any text-completion function. Keeps the router free of provider SDKs. */
|
|
50
|
+
export type Complete = (prompt: string) => Promise<string>;
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|