skill-autoroute 0.8.0 → 0.9.0
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 +20 -1
- package/hook/route.js +80 -12
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -58,6 +58,25 @@ The hook remembers which skills it already named in a session (in `~/.config/ski
|
|
|
58
58
|
after 7 days). A later prompt, or a resumed round of a headless run (`claude -p --resume`), does not hint them again.
|
|
59
59
|
`suggest` always answers and adds what it names to that memory.
|
|
60
60
|
|
|
61
|
+
**Machine-readable mode.** For a loop that knows its task as data, pass a JSON file (or `-` for stdin):
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
echo '{"schema_version":1,"session_id":"s1","stage":"build","task":{"title":"write the orders migration","tags":["db"]},"policy":{"max_skills":2,"skip":["x"]}}' \
|
|
65
|
+
| node ~/.config/skill-autoroute/route.mjs claude suggest --json --context-file -
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Input: `schema_version` must be `1`; `session_id`, `stage`, `role`, `task.{title,summary,tags}` and `policy.{max_skills (1 to 3), skip}` are optional.
|
|
69
|
+
The file is at most 20000 characters. Stage, role, title, summary and tags are joined into the match text. Every string is data: it is matched
|
|
70
|
+
against trigger patterns and never run. Output is one JSON line, always exit 0, and no model is called:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{"schema_version":1,"status":"ok","selected":[{"id":"skill","path":"/.../SKILL.md","scope":"global","reason_code":"pattern"}],"suppressed":[{"id":"x","reason_code":"skip_list"}],"routing_version":"1a2b3c4d5e6f","duration_ms":3}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`status` is `ok`, `no_match` (`selected` is empty) or `error` (`{"schema_version":1,"status":"error","error":"bad_schema_version"}`; codes: `bad_args`, `unreadable`, `too_large`, `bad_json`, `not_object`, `bad_schema_version`).
|
|
77
|
+
`reason_code` is `own_words` (the skill's own trigger words) or `pattern`; `scope` is `project` for a skill limited to project folders. `suppressed` lists matching skills left out as `seen_in_session`, `skip_list` or `duplicate_name`.
|
|
78
|
+
SKILL.md contents are never returned. On `ok`, the selected names go into the session memory like text-mode `suggest`.
|
|
79
|
+
|
|
61
80
|
---
|
|
62
81
|
|
|
63
82
|
## Quick start
|
|
@@ -340,7 +359,7 @@ Paths are stored relative to the project, and entries that point outside the pro
|
|
|
340
359
|
- Project tables can arrive with a clone, so the hook re-checks them. It skips risky patterns and entries outside the
|
|
341
360
|
project, and it cleans skill names.
|
|
342
361
|
- It reads at most 20,000 characters of the prompt.
|
|
343
|
-
- `SKILL_AUTOROUTE_DISABLE=1` turns it off. `SKILL_AUTOROUTE_DEBUG=1` prints errors.
|
|
362
|
+
- `SKILL_AUTOROUTE_DISABLE=1` turns it off. `SKILL_AUTOROUTE_DEBUG=1` prints errors. `SKILL_AUTOROUTE_RANK=score` ranks hints by score (own words, rules that fit, pattern specificity) instead of the static priority number. Opt-in: on a synthetic corpus it raised precision@1, but on a hand-labeled set of real skills it made no difference.
|
|
344
363
|
|
|
345
364
|
</details>
|
|
346
365
|
|
package/hook/route.js
CHANGED
|
@@ -4,6 +4,7 @@ import { readFileSync, statSync, readdirSync, realpathSync, appendFileSync, mkdi
|
|
|
4
4
|
import { join, dirname, resolve, sep } from 'node:path';
|
|
5
5
|
import { homedir } from 'node:os';
|
|
6
6
|
import { pathToFileURL } from 'node:url';
|
|
7
|
+
import { createRequire } from 'node:module';
|
|
7
8
|
|
|
8
9
|
const MAX_PROMPT = 20000; // defence in depth against a slow pattern
|
|
9
10
|
const MAX_HINTS = 3;
|
|
@@ -109,18 +110,31 @@ const compile = (src) => {
|
|
|
109
110
|
try { return new RegExp(src, 'i'); } catch { return null; }
|
|
110
111
|
};
|
|
111
112
|
|
|
112
|
-
// A rule fits when all its patterns match; a rule with a skipped pattern never fits.
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
113
|
+
// A rule fits when all its patterns match; a rule with a skipped pattern never fits. Returns null, or
|
|
114
|
+
// { rules, pats, chars } for the fitting rules (pats/chars: the best rule's pattern count and matched characters).
|
|
115
|
+
// `all` false stops at the first fitting rule (priority ranking only needs a boolean); true counts every rule.
|
|
116
|
+
function fits(rules, text, all = false) {
|
|
117
|
+
if (!Array.isArray(rules)) return null;
|
|
118
|
+
let best = null;
|
|
119
|
+
for (const rule of rules) {
|
|
120
|
+
if (!Array.isArray(rule) || !rule.length) continue;
|
|
121
|
+
let chars = 0;
|
|
117
122
|
for (const src of rule) {
|
|
118
123
|
const re = compile(src);
|
|
119
|
-
|
|
124
|
+
const m = re && re.exec(text);
|
|
125
|
+
if (!m) { chars = -1; break; }
|
|
126
|
+
chars += m[0].length;
|
|
120
127
|
}
|
|
121
|
-
|
|
122
|
-
|
|
128
|
+
if (chars < 0) continue;
|
|
129
|
+
best ||= { rules: 0, pats: 0, chars: 0 };
|
|
130
|
+
best.rules++;
|
|
131
|
+
if (rule.length > best.pats || (rule.length === best.pats && chars > best.chars)) { best.pats = rule.length; best.chars = chars; }
|
|
132
|
+
if (!all) return best;
|
|
133
|
+
}
|
|
134
|
+
return best;
|
|
123
135
|
}
|
|
136
|
+
// Score ranking: own-words hit dominates, then rules that fit and patterns in the best rule, then matched characters.
|
|
137
|
+
const score = (own, f) => own * 1e9 + (f ? (f.rules + f.pats) * 1e4 + Math.min(f.chars, 9999) : 0);
|
|
124
138
|
|
|
125
139
|
// Own words are literal text, so they cannot carry a slow pattern. Edges are lookarounds, not \b, so "c++" still matches.
|
|
126
140
|
export function wordsPattern(words) {
|
|
@@ -176,7 +190,7 @@ const inProject = (s, here, fs) => !Array.isArray(s.projects) || s.projects.some
|
|
|
176
190
|
return here.some((h) => h === root || h.startsWith(root + sep));
|
|
177
191
|
});
|
|
178
192
|
|
|
179
|
-
function pick(prompt, table, { tool, base, skip, fs = FS } = {}) {
|
|
193
|
+
export function pick(prompt, table, { tool, base, skip, fs = FS, rank = process.env.SKILL_AUTOROUTE_RANK } = {}) {
|
|
180
194
|
const text = String(prompt).slice(0, MAX_PROMPT);
|
|
181
195
|
const here = places(base, fs);
|
|
182
196
|
const ok = (v) => typeof v === 'string' && v !== '';
|
|
@@ -184,8 +198,11 @@ function pick(prompt, table, { tool, base, skip, fs = FS } = {}) {
|
|
|
184
198
|
const hits = table.skills
|
|
185
199
|
.filter((s) => s && s.enabled && ok(s.name) && ok(s.path) && /[\\/]SKILL\.md$/.test(s.path) && (!tool || (Array.isArray(s.tools) ? s.tools : [s.tool]).includes(tool)) && inProject(s, here, fs))
|
|
186
200
|
.map((s) => ({ s, own: ownFits(s, text) }))
|
|
187
|
-
.
|
|
188
|
-
.
|
|
201
|
+
.map((e) => (rank === 'score' ? { ...e, f: fits(e.s.patterns, text, true) } : e))
|
|
202
|
+
.filter((e) => (e.own || (rank === 'score' ? e.f : fits(e.s.patterns, text))) && fs.mtime(e.s.path) !== null)
|
|
203
|
+
.sort(rank === 'score'
|
|
204
|
+
? (a, b) => (score(b.own, b.f) - score(a.own, a.f)) || ((a.s.priority ?? 1e9) - (b.s.priority ?? 1e9)) || (a.s.name < b.s.name ? -1 : a.s.name > b.s.name ? 1 : 0)
|
|
205
|
+
: (a, b) => (b.own - a.own) || ((a.s.priority ?? 1e9) - (b.s.priority ?? 1e9)))
|
|
189
206
|
.map(({ s }) => s)
|
|
190
207
|
.filter((s) => !seen.has(s.name) && seen.add(s.name) && !skip?.has(s.name))
|
|
191
208
|
.slice(0, MAX_HINTS);
|
|
@@ -194,7 +211,7 @@ function pick(prompt, table, { tool, base, skip, fs = FS } = {}) {
|
|
|
194
211
|
let out = 'Skills that fit this work (read each SKILL.md before you start): ' + hits.map((s) => `${shownName(s.name)} (${safe(s.path)})`).join('; ') + '.';
|
|
195
212
|
const n = staleCount(table, fs);
|
|
196
213
|
if (n) out += `\n${n} skill${n === 1 ? '' : 's'} changed since the last generate. Run: npx skill-autoroute regenerate`;
|
|
197
|
-
return { out, count: hits.length, names: hits.map((s) => s.name) };
|
|
214
|
+
return { out, count: hits.length, names: hits.map((s) => s.name), detail: hits.map((s) => ({ name: s.name, path: s.path, own: ownFits(s, text), scope: Array.isArray(s.projects) ? 'project' : 'global' })) };
|
|
198
215
|
}
|
|
199
216
|
|
|
200
217
|
export const route = (prompt, table, opts) => pick(prompt, table, opts)?.out ?? null;
|
|
@@ -275,6 +292,7 @@ const loadTable = (udir, base) => merge(load(join(udir, 'routes.json')), resolve
|
|
|
275
292
|
|
|
276
293
|
// `route.mjs [tool] suggest <session|-> <text...>`: the agent asks for skills in the middle of its work.
|
|
277
294
|
function suggest(udir, args, i) {
|
|
295
|
+
if (args[i + 1] === '--json') return suggestJson(udir, args, i);
|
|
278
296
|
const tool = i === 1 ? args[0] : undefined;
|
|
279
297
|
const base = process.env.CLAUDE_PROJECT_DIR || process.cwd();
|
|
280
298
|
const table = loadTable(udir, base);
|
|
@@ -283,6 +301,56 @@ function suggest(udir, args, i) {
|
|
|
283
301
|
if (hit) remember(sessionFile(udir, tool, args[i + 1]), hit.names);
|
|
284
302
|
}
|
|
285
303
|
|
|
304
|
+
// `suggest --json --context-file <path|->`: the same pick, driven by a JSON task description and answered as one JSON line.
|
|
305
|
+
// Every string in the file is data: it is only matched against trigger patterns, never run or put in a shell.
|
|
306
|
+
function suggestJson(udir, args, i) {
|
|
307
|
+
const t0 = Date.now();
|
|
308
|
+
const tool = i === 1 ? args[0] : undefined;
|
|
309
|
+
const done = (o) => process.stdout.write(`${JSON.stringify({ schema_version: 1, ...o, duration_ms: Date.now() - t0 })}\n`);
|
|
310
|
+
const fail = (error) => done({ status: 'error', error });
|
|
311
|
+
const f = args[i + 2] === '--context-file' ? args[i + 3] : undefined;
|
|
312
|
+
if (!f) return fail('bad_args');
|
|
313
|
+
let raw;
|
|
314
|
+
try { raw = readFileSync(f === '-' ? 0 : f, 'utf8'); } catch { return fail('unreadable'); }
|
|
315
|
+
if (raw.length > MAX_PROMPT) return fail('too_large');
|
|
316
|
+
let c;
|
|
317
|
+
try { c = JSON.parse(raw); } catch { return fail('bad_json'); }
|
|
318
|
+
if (!c || typeof c !== 'object' || Array.isArray(c)) return fail('not_object');
|
|
319
|
+
if (c.schema_version !== 1) return fail('bad_schema_version');
|
|
320
|
+
const str = (v) => (typeof v === 'string' ? v : '');
|
|
321
|
+
const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
|
|
322
|
+
const task = c.task && typeof c.task === 'object' ? c.task : {};
|
|
323
|
+
const policy = c.policy && typeof c.policy === 'object' ? c.policy : {};
|
|
324
|
+
const text = [str(c.stage), str(c.role), str(task.title), str(task.summary), strs(task.tags).join(' ')].filter(Boolean).join(' ');
|
|
325
|
+
const max = Number.isInteger(policy.max_skills) ? Math.min(MAX_HINTS, Math.max(1, policy.max_skills)) : MAX_HINTS;
|
|
326
|
+
const file = sessionFile(udir, tool, c.session_id);
|
|
327
|
+
const known = (file && remembered(file)) || new Set();
|
|
328
|
+
const skipList = new Set(strs(policy.skip));
|
|
329
|
+
const base = process.env.CLAUDE_PROJECT_DIR || process.cwd();
|
|
330
|
+
const table = loadTable(udir, base);
|
|
331
|
+
const hit = table && pick(text, table, { tool, base, skip: new Set([...skipList, ...known]) });
|
|
332
|
+
const detail = hit ? hit.detail.slice(0, max) : [];
|
|
333
|
+
const selected = detail.map((d) => ({ id: shownName(d.name), path: d.path, scope: d.scope, reason_code: d.own ? 'own_words' : 'pattern' }));
|
|
334
|
+
// Suppressed: skills that matched this text but were left out for a reason that is cheap to know.
|
|
335
|
+
const suppressed = [];
|
|
336
|
+
if (table) {
|
|
337
|
+
const here = places(base, FS);
|
|
338
|
+
const names = new Set();
|
|
339
|
+
for (const s of table.skills) {
|
|
340
|
+
if (!s.enabled || typeof s.name !== 'string' || !s.name || typeof s.path !== 'string' || !/[\\/]SKILL\.md$/.test(s.path)) continue;
|
|
341
|
+
if ((tool && !(Array.isArray(s.tools) ? s.tools : [s.tool]).includes(tool)) || !inProject(s, here, FS)) continue;
|
|
342
|
+
if (!(ownFits(s, text) || fits(s.patterns, text)) || FS.mtime(s.path) === null) continue;
|
|
343
|
+
const reason_code = names.has(s.name) ? 'duplicate_name' : skipList.has(s.name) ? 'skip_list' : known.has(s.name) ? 'seen_in_session' : null;
|
|
344
|
+
names.add(s.name);
|
|
345
|
+
if (reason_code && suppressed.length < 20) suppressed.push({ id: shownName(s.name), reason_code });
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
// crypto loads only here: a static import adds ~5 ms to every prompt's cold start.
|
|
349
|
+
const routing_version = createRequire(import.meta.url)('node:crypto').createHash('sha256').update(`${table?.generatedAt}${table?.skills.length}`).digest('hex').slice(0, 12);
|
|
350
|
+
done({ status: selected.length ? 'ok' : 'no_match', selected, suppressed, routing_version });
|
|
351
|
+
if (selected.length) remember(file, detail.map((d) => d.name));
|
|
352
|
+
}
|
|
353
|
+
|
|
286
354
|
function main(self) {
|
|
287
355
|
if (process.env.SKILL_AUTOROUTE_DISABLE === '1') return;
|
|
288
356
|
const udir = join(homedir(), '.config', 'skill-autoroute');
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "skill-autoroute",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Per-prompt skill router hook for Claude Code and Codex",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude-code",
|
|
@@ -34,7 +34,8 @@
|
|
|
34
34
|
"skill"
|
|
35
35
|
],
|
|
36
36
|
"scripts": {
|
|
37
|
-
"test": "node --test test/*.test.js"
|
|
37
|
+
"test": "node --test test/*.test.js",
|
|
38
|
+
"eval": "node test/eval/run.js"
|
|
38
39
|
},
|
|
39
40
|
"license": "MIT",
|
|
40
41
|
"dependencies": {
|