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.
Files changed (3) hide show
  1. package/README.md +20 -1
  2. package/hook/route.js +80 -12
  3. 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
- function fits(rules, text) {
114
- if (!Array.isArray(rules)) return false;
115
- return rules.some((rule) => {
116
- if (!Array.isArray(rule) || !rule.length) return false;
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
- if (!re || !re.test(text)) return false;
124
+ const m = re && re.exec(text);
125
+ if (!m) { chars = -1; break; }
126
+ chars += m[0].length;
120
127
  }
121
- return true;
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
- .filter(({ s, own }) => (own || fits(s.patterns, text)) && fs.mtime(s.path) !== null)
188
- .sort((a, b) => (b.own - a.own) || ((a.s.priority ?? 1e9) - (b.s.priority ?? 1e9)))
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.8.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": {