skill-autoroute 0.3.0 โ 0.4.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 +52 -1
- package/bin/cli.js +2 -2
- package/hook/route.js +15 -2
- package/package.json +1 -1
- package/src/flow.js +42 -3
- package/src/triggers.js +3 -1
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
|
-
| ๐ธ **
|
|
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: 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:
|
|
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
|
-
.
|
|
156
|
-
.
|
|
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
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
|
-
|
|
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.
|