skill-autoroute 0.3.0 โ†’ 0.4.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 CHANGED
@@ -102,7 +102,7 @@ prefer to install them as a skill.
102
102
  | ๐Ÿ”‘ **No API key** | Uses the `claude` or `codex` CLI you are already logged in to. |
103
103
  | ๐Ÿ›ก๏ธ **Security scan** | Flags remote code runs, hidden text, prompt injection, secret theft, and more. |
104
104
  | ๐Ÿ‘ฏ **Duplicate check** | Finds look-alike skills, and the AI says which is better and why. You still decide. |
105
- | ๐Ÿ’ธ **Small models** | Haiku or a small Codex model for triggers. Sonnet or a mid Codex model for judgment. Never the top model. |
105
+ | ๐Ÿ’ธ **No top model** | Sonnet or a mid Codex model writes triggers and judges skills. Haiku or a small model checks the login. Never the top model. |
106
106
  | ๐Ÿ“Š **Real token numbers** | Shows the estimate first, then the real usage. Saved in `install-report.json`. |
107
107
  | ๐Ÿงน **Clean uninstall** | Removes only its own hook entries. Your other hooks stay. |
108
108
 
@@ -180,6 +180,56 @@ codex-cli 0.164.0. Your numbers will differ.
180
180
 
181
181
  ---
182
182
 
183
+ ## Hint quality
184
+
185
+ A wrong hint costs tokens and teaches the agent to ignore hints, so the trigger rules aim for precise hints, not many
186
+ hints. Measured on 2026-10-28 on 1,616 real prompts from one developer's Claude Code history, with 148 installed skills.
187
+ Sonnet graded 90 sampled prompts blind (was each hinted skill useful for that prompt?). A fixed check has 13 prompts with
188
+ a known answer, 5 of which must get no hint.
189
+
190
+
191
+ | Trigger rules | Precision | Relative recall | Useful / wrong hints | Hint tokens per prompt | Fixed check |
192
+ | ------------------------------------------ | --------- | --------------- | -------------------- | ---------------------- | ----------- |
193
+ | 0.2.0 (haiku) | 35.5% | 50.0% | 22 / 40 | 12.9 | 10/13 |
194
+ | Broad single-word rules (haiku) | 21.0% | 59.1% | 26 / 98 | 24.1 | 9/13 |
195
+ | **0.3.0 and later: task word plus object word (sonnet)** | **59.1%** | **59.1%** | **26 / 18** | **10.8** | **12/13** |
196
+
197
+
198
+ Relative recall is the share of all useful hints that any version found. Broader rules doubled the hints but most of the
199
+ new ones were wrong. Guessing the kind of work from the prompt (question, change, risky) to gate or add hints was also
200
+ tested and made hints worse (F1 63.2 down to 55.7), so it is not used.
201
+
202
+ Examples with 0.3.0 and later (0.4.0 added [your own trigger words](#your-own-trigger-words); the rules are the same):
203
+
204
+ | Prompt | Hint |
205
+ | ------------------------------------- | ----------------------- |
206
+ | add a column to the users table | `database-migrations` |
207
+ | make this landing page responsive | `impeccable` |
208
+ | add a webhook endpoint to the API | `api-design` |
209
+ | write a PR description | `pr-description` |
210
+ | yes / continue / ok now ask the agent | no hint |
211
+
212
+ When a rule misses a phrase you use, add [your own trigger words](#your-own-trigger-words).
213
+
214
+ ---
215
+
216
+ ## Your own trigger words
217
+
218
+ The AI-written rules miss some phrasings. Add the words you really type:
219
+
220
+ ```bash
221
+ npx skill-autoroute words no-ai-slop add polish proofread "README text"
222
+ npx skill-autoroute words # list every skill's own words
223
+ npx skill-autoroute words no-ai-slop remove polish
224
+ ```
225
+
226
+ - Each word or phrase matches as a whole word, case-insensitive. It is plain text, not a regex.
227
+ - A match on your own words puts that skill first among the hints.
228
+ - `regenerate` and `install` keep your words. Up to 20 per skill, 60 characters each.
229
+ - A word that also fires on ordinary replies (for example `fix` in "please fix this") is allowed, with a warning.
230
+
231
+ ---
232
+
183
233
  ## Models
184
234
 
185
235
 
@@ -208,6 +258,7 @@ npx skill-autoroute install --model triggers=haiku
208
258
  | `regenerate` | Update triggers for new or changed skills, or for all skills after an update that changes how triggers are written. Keeps your choices. |
209
259
  | `scan` | Scan and find duplicates only. Writes nothing. |
210
260
  | `set <skill> on|off` | Turn one skill's hints on or off |
261
+ | `words [<skill> [add|remove <word>...]]` | Your own trigger words for a skill. Without a skill, lists all of them. |
211
262
  | `status` | Tools, hook state, skill counts, changed skills |
212
263
  | `tokens` | Hint size per skill and usage log summary |
213
264
  | `bench` | Measure the hook's real token cost |
package/bin/cli.js CHANGED
@@ -6,11 +6,11 @@ import * as flow from '../src/flow.js';
6
6
  import { STEP_DEFAULTS } from '../src/models.js';
7
7
 
8
8
  const USAGE = `usage: skill-autoroute <command> [flags]
9
- commands: install | regenerate | scan | set <skill> on|off | status | tokens | bench | uninstall
9
+ commands: install | regenerate | scan | set <skill> on|off | words [<skill> [add|remove <word>...]] | status | tokens | bench | uninstall
10
10
  flags: --yes --dry-run --project --tools claude,codex --ai claude|codex|none --model step=model (repeatable) --log`;
11
11
 
12
12
  const COMMANDS = {
13
- install: flow.install, regenerate: flow.regenerate, scan: flow.scan, set: flow.setSkill,
13
+ install: flow.install, regenerate: flow.regenerate, scan: flow.scan, set: flow.setSkill, words: flow.setWords,
14
14
  status: flow.status, tokens: flow.tokens, bench: flow.bench, uninstall: flow.uninstall,
15
15
  };
16
16
 
package/hook/route.js CHANGED
@@ -9,6 +9,8 @@ const MAX_PROMPT = 20000; // defence in depth against a slow pattern
9
9
  const MAX_HINTS = 3;
10
10
  const MAX_PATTERN = 300; // same limit as src/validate.js
11
11
  const MAX_NAME = 100;
12
+ const MAX_WORDS = 20; // own trigger words per skill (`skill-autoroute words`)
13
+ const MAX_WORD = 60;
12
14
 
13
15
  // Real file system; tests pass fakes. mtime is null when the path is missing.
14
16
  const FS = {
@@ -120,6 +122,15 @@ function fits(rules, text) {
120
122
  });
121
123
  }
122
124
 
125
+ // Own words are literal text, so they cannot carry a slow pattern. Edges are lookarounds, not \b, so "c++" still matches.
126
+ export function wordsPattern(words) {
127
+ if (!Array.isArray(words)) return null;
128
+ const ok = words.filter((w) => typeof w === 'string' && w.trim() && w.length <= MAX_WORD).slice(0, MAX_WORDS);
129
+ if (!ok.length) return null;
130
+ return `(?<!\\w)(${ok.map((w) => w.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+')).join('|')})(?!\\w)`;
131
+ }
132
+ const ownFits = (s, text) => { const src = wordsPattern(s.words); return Boolean(src && new RegExp(src, 'i').test(text)); };
133
+
123
134
  // Stale: a table skill whose SKILL.md is gone or newer than the table (project entries: gone only, since a clone or
124
135
  // pull resets file times past the committed generatedAt), plus a skill folder in a root that the table
125
136
  // does not know (table paths are real paths; root entries are often symlinks, so they are resolved first).
@@ -152,8 +163,10 @@ function pick(prompt, table, { tool, fs = FS } = {}) {
152
163
  const seen = new Set();
153
164
  const hits = table.skills
154
165
  .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)))
155
- .filter((s) => fits(s.patterns, text) && fs.mtime(s.path) !== null)
156
- .sort((a, b) => (a.priority ?? 1e9) - (b.priority ?? 1e9))
166
+ .map((s) => ({ s, own: ownFits(s, text) }))
167
+ .filter(({ s, own }) => (own || fits(s.patterns, text)) && fs.mtime(s.path) !== null)
168
+ .sort((a, b) => (b.own - a.own) || ((a.s.priority ?? 1e9) - (b.s.priority ?? 1e9)))
169
+ .map(({ s }) => s)
157
170
  .filter((s) => !seen.has(s.name) && seen.add(s.name))
158
171
  .slice(0, MAX_HINTS);
159
172
  if (!hits.length) return null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "skill-autoroute",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "Per-prompt skill router hook for Claude Code and Codex",
5
5
  "keywords": [
6
6
  "claude-code",
package/src/flow.js CHANGED
@@ -8,14 +8,13 @@ import { discover } from './discover.js';
8
8
  import { scanStatic, label } from './scan/static.js';
9
9
  import { aiScan, mergeScan } from './scan/ai.js';
10
10
  import { candidateGroups, aiDedupe, MAX_GROUP } from './dedupe.js';
11
- import { aiTriggers, keywordRules, TRIGGER_PROMPT } from './triggers.js';
11
+ import { aiTriggers, keywordRules, TRIGGER_PROMPT, RULES_VERSION, genericMatch } from './triggers.js';
12
12
  import { estimate, Recorder, formatReport, writeReport, hookReport, num } from './usage.js';
13
13
  import { readTable, writeTable, mergeTables } from './table.js';
14
14
  import { pickModel } from './models.js';
15
- import { RULES_VERSION } from './triggers.js';
16
15
  import { routesPath, reportPath, hookCopyPath, logPath } from './paths.js';
17
16
  import { installHookCopy, hookCommand, checkConfig } from './tools/hookconfig.js';
18
- import { route, staleCount, resolveProject } from '../hook/route.js';
17
+ import { route, staleCount, resolveProject, wordsPattern } from '../hook/route.js';
19
18
 
20
19
  export const ADAPTERS = { claude, codex };
21
20
  export class Cancel extends Error {}
@@ -294,6 +293,7 @@ export async function install(o, ui) {
294
293
  const rows = await pickRows(buildRows(skills, scans, await runDedupe(skills, ctx, ui)), ui);
295
294
  const gen = await generate(rows.filter((r) => r.enabled).map((r) => r.skill), ctx, ui);
296
295
  const table = tableOf(ctx, rows.map((r) => entry(r, gen, scope)), roots.map(keyOf(scope)), o.log);
296
+ keepWords(table, readTable(routesPath(scope)));
297
297
  while (!ui.yes) {
298
298
  const p = await ui.text('Preview: type a prompt to see its hints (empty to finish)');
299
299
  if (!p) break;
@@ -347,6 +347,7 @@ export async function regenerate(o, ui) {
347
347
  byPath.set(s.skillPath, { ...was(s), priority: g?.priority ?? 50, patterns: g?.rules ?? [] });
348
348
  }
349
349
  const table = tableOf(ctx, skills.map((s) => byPath.get(s.skillPath) ?? was(s)), roots.map(key), old.log);
350
+ keepWords(table, old);
350
351
  // unchanged rules still come from the old generator; after a full rebuild the new model wrote them all
351
352
  if (!o.ai && old.generator) table.generator = { ...old.generator, rules: RULES_VERSION, ...(outdated && ctx.ai ? { model: table.generator.model } : {}) };
352
353
  printRows(rows, ui);
@@ -356,6 +357,44 @@ export async function regenerate(o, ui) {
356
357
  summary(ctx, gen, [], ui);
357
358
  }
358
359
 
360
+ // Own trigger words belong to the user: a rebuilt table takes them over by skill path.
361
+ function keepWords(table, old) {
362
+ const words = new Map((old?.skills ?? []).filter((s) => Array.isArray(s.words) && s.words.length).map((s) => [s.path, s.words]));
363
+ for (const s of table.skills) if (words.has(s.path)) s.words = words.get(s.path);
364
+ }
365
+
366
+ const MAX_OWN_WORDS = 20;
367
+ const MAX_OWN_WORD = 60;
368
+ export function setWords(o, ui, name, action, ...words) {
369
+ const p = routesPath(scopeOf(o));
370
+ const t = readTable(p);
371
+ if (!t) throw new Error(`no table at ${show(p)}; run install first`);
372
+ if (!name) {
373
+ const own = t.skills.filter((s) => s.words?.length);
374
+ if (!own.length) ui.log('No own trigger words yet. Add some: npx skill-autoroute words <skill> add <word> [more words]');
375
+ for (const s of own) ui.log(`${show(s.name)}: ${s.words.map(show).join(', ')}`);
376
+ return;
377
+ }
378
+ const hits = t.skills.filter((s) => s.name === name);
379
+ if (!hits.length) throw new Error(`no skill named "${show(name)}" in ${show(p)}`);
380
+ if (!action) return ui.log(`${show(name)}: ${hits[0].words?.map(show).join(', ') || 'no own words'}`);
381
+ if (!['add', 'remove'].includes(action) || !words.length) throw new Error('usage: skill-autoroute words [<skill> [add|remove <word> [more words]]]');
382
+ const clean = words.map((w) => w.trim().replace(/\s+/g, ' '));
383
+ if (clean.some((w) => !w || w.length > MAX_OWN_WORD || /[\u0000-\u001f\u007f]/.test(w))) throw new Error(`each word or phrase must be 1 to ${MAX_OWN_WORD} characters of plain text`);
384
+ for (const s of hits) {
385
+ const now = s.words ?? [];
386
+ const next = action === 'add' ? [...new Set([...now, ...clean])] : now.filter((w) => !clean.includes(w));
387
+ if (next.length > MAX_OWN_WORDS) throw new Error(`a skill can have at most ${MAX_OWN_WORDS} own words; ${show(name)} would have ${next.length}`);
388
+ if (next.length) s.words = next; else delete s.words;
389
+ }
390
+ writeTable(p, t);
391
+ const list = hits[0].words ?? [];
392
+ ui.log(`${show(name)}: ${list.map(show).join(', ') || 'no own words'}`);
393
+ const generic = list.length && genericMatch([wordsPattern(list)]);
394
+ if (generic) ui.log(`Warning: these words also fire on ordinary replies such as "${generic}", so ${show(name)} will be hinted often.`);
395
+ if (hits.every((s) => !s.enabled)) ui.log(`${show(name)} is off, so it gets no hints. Run: npx skill-autoroute set ${show(name)} on`);
396
+ }
397
+
359
398
  export function setSkill(o, ui, name, state) {
360
399
  if (!name || !['on', 'off'].includes(state)) throw new Error('usage: skill-autoroute set <skill> on|off');
361
400
  const p = routesPath(scopeOf(o));
package/src/triggers.js CHANGED
@@ -19,7 +19,9 @@ export const STOP_WORDS = new Set(`${BASE_STOP} ${MORE_STOP}`.split(/\s+/));
19
19
  // R29: a rule that fires on any of these is a catch-all and is dropped.
20
20
  const GENERIC_PROMPTS = ['hello', 'thanks', 'go ahead', 'please fix this', 'yes', 'continue', 'sounds good', 'ok do it',
21
21
  'fix it', 'run it', 'check this', 'ask the agent', 'use the workflow', 'look at the spec', 'open the chat', 'build it'];
22
- const isGeneric = (rule) => GENERIC_PROMPTS.some((t) => rule.every((p) => new RegExp(p, 'i').test(t)));
22
+ // The first generic prompt the rule fires on, or undefined.
23
+ export const genericMatch = (rule) => GENERIC_PROMPTS.find((t) => rule.every((p) => new RegExp(p, 'i').test(t)));
24
+ const isGeneric = (rule) => genericMatch(rule) !== undefined;
23
25
  const CONTROL = /[\u0000-\u001f]/;
24
26
  const MAX_RULES = 6;
25
27
  // Bump when TRIGGER_PROMPT or rule limits change: regenerate then rebuilds every skill's rules.