skill-autoroute 0.5.0 → 0.7.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 +31 -2
- package/bin/cli.js +2 -2
- package/hook/route.js +54 -10
- package/package.json +1 -1
- package/src/flow.js +18 -0
package/README.md
CHANGED
|
@@ -45,6 +45,19 @@ No match means no output and **0 extra tokens**. No AI runs at prompt time. The
|
|
|
45
45
|
|
|
46
46
|

|
|
47
47
|
|
|
48
|
+
### 3 · During the work (agent loops)
|
|
49
|
+
|
|
50
|
+
The hook fires only when a prompt arrives, not on every step of an agent loop. So the first prompt of each session
|
|
51
|
+
also tells the agent how to ask for skills itself before a new sub-task:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
node ~/.config/skill-autoroute/route.mjs claude suggest <session-id> "write the migration for the orders table"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The hook remembers which skills it already named in a session (in `~/.config/skill-autoroute/sessions/`, pruned
|
|
58
|
+
after 7 days). A later prompt, or a resumed round of a headless run (`claude -p --resume`), does not hint them again.
|
|
59
|
+
`suggest` always answers and adds what it names to that memory.
|
|
60
|
+
|
|
48
61
|
---
|
|
49
62
|
|
|
50
63
|
## Quick start
|
|
@@ -151,8 +164,10 @@ The router **adds** tokens. It does not save them. It pays off when a hint makes
|
|
|
151
164
|
|
|
152
165
|
| When | Cost |
|
|
153
166
|
| ------------------------------------------ | -------------------------------------------------------------- |
|
|
154
|
-
| A prompt matches nothing | **0 tokens**
|
|
167
|
+
| A prompt matches nothing | **0 tokens** (the first prompt of a session: the `suggest` line, about 40 tokens) |
|
|
155
168
|
| A prompt matches | one line, about 50–70 tokens per skill, at most 3 skills |
|
|
169
|
+
| A skill already named in this session | **0 tokens**: not hinted again |
|
|
170
|
+
| The agent runs `suggest` | one tool call plus the same hint line |
|
|
156
171
|
| Install (example: 7 skills, `--ai claude`) | 58,350 input tokens against an estimate of 58,200, in 11 calls |
|
|
157
172
|
|
|
158
173
|
|
|
@@ -257,6 +272,7 @@ npx skill-autoroute install --model triggers=haiku
|
|
|
257
272
|
| `install` | The full setup flow |
|
|
258
273
|
| `regenerate` | Update triggers for new or changed skills, or for all skills after an update that changes how triggers are written. Keeps your choices. |
|
|
259
274
|
| `scan` | Scan and find duplicates only. Writes nothing. |
|
|
275
|
+
| `list` | Show skills, on/off state, tools, priority, paths and trigger rules. Supports `--tools` and `--project`. Writes nothing. |
|
|
260
276
|
| `set <skill> on|off` | Turn one skill's hints on or off |
|
|
261
277
|
| `words [<skill> [add|remove <word>...]]` | Your own trigger words for a skill. Without a skill, lists all of them. |
|
|
262
278
|
| `status` | Tools, hook state, skill counts, changed skills |
|
|
@@ -270,6 +286,19 @@ npx skill-autoroute install --model triggers=haiku
|
|
|
270
286
|
|
|
271
287
|
When your skills change, the hint line tells you so. Run `regenerate`.
|
|
272
288
|
|
|
289
|
+
Inspect the saved routing configuration:
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
npx skill-autoroute list
|
|
293
|
+
npx skill-autoroute list --tools codex
|
|
294
|
+
npx skill-autoroute list --project
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
`list` reads the user table by default; `--project` reads only the current project's table.
|
|
298
|
+
It includes disabled skills (marked `off`). Patterns within a rule must all match (AND);
|
|
299
|
+
any rule can trigger the skill (OR). Custom words are another way to match.
|
|
300
|
+
Enabled means eligible for routing on matching prompts, not that the agent has invoked the skill.
|
|
301
|
+
|
|
273
302
|
---
|
|
274
303
|
|
|
275
304
|
## User or project install
|
|
@@ -330,4 +359,4 @@ The tests use fake `claude` and `codex` programs and a fake `HOME`. They make no
|
|
|
330
359
|
|
|
331
360
|
## License
|
|
332
361
|
|
|
333
|
-
[MIT](LICENSE)
|
|
362
|
+
[MIT](LICENSE)
|
package/bin/cli.js
CHANGED
|
@@ -6,12 +6,12 @@ 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 | words [<skill> [add|remove <word>...]] | status | tokens | bench | uninstall
|
|
9
|
+
commands: install | regenerate | scan | list | 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
13
|
install: flow.install, regenerate: flow.regenerate, scan: flow.scan, set: flow.setSkill, words: flow.setWords,
|
|
14
|
-
status: flow.status, tokens: flow.tokens, bench: flow.bench, uninstall: flow.uninstall,
|
|
14
|
+
list: flow.list, status: flow.status, tokens: flow.tokens, bench: flow.bench, uninstall: flow.uninstall,
|
|
15
15
|
};
|
|
16
16
|
|
|
17
17
|
function options() {
|
package/hook/route.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// Per-prompt hook for Claude Code and Codex. Node built-ins only; any error means no output, exit 0.
|
|
2
2
|
// argv[2] names the tool (claude or codex): only that tool's skills are hinted; no argument hints all.
|
|
3
|
-
import { readFileSync, statSync, readdirSync, realpathSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
|
|
3
|
+
import { readFileSync, statSync, readdirSync, realpathSync, appendFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
|
|
4
4
|
import { join, dirname, resolve, sep } from 'node:path';
|
|
5
5
|
import { homedir } from 'node:os';
|
|
6
6
|
import { pathToFileURL } from 'node:url';
|
|
@@ -176,7 +176,7 @@ const inProject = (s, here, fs) => !Array.isArray(s.projects) || s.projects.some
|
|
|
176
176
|
return here.some((h) => h === root || h.startsWith(root + sep));
|
|
177
177
|
});
|
|
178
178
|
|
|
179
|
-
function pick(prompt, table, { tool, base, fs = FS } = {}) {
|
|
179
|
+
function pick(prompt, table, { tool, base, skip, fs = FS } = {}) {
|
|
180
180
|
const text = String(prompt).slice(0, MAX_PROMPT);
|
|
181
181
|
const here = places(base, fs);
|
|
182
182
|
const ok = (v) => typeof v === 'string' && v !== '';
|
|
@@ -187,14 +187,14 @@ function pick(prompt, table, { tool, base, fs = FS } = {}) {
|
|
|
187
187
|
.filter(({ s, own }) => (own || fits(s.patterns, text)) && fs.mtime(s.path) !== null)
|
|
188
188
|
.sort((a, b) => (b.own - a.own) || ((a.s.priority ?? 1e9) - (b.s.priority ?? 1e9)))
|
|
189
189
|
.map(({ s }) => s)
|
|
190
|
-
.filter((s) => !seen.has(s.name) && seen.add(s.name))
|
|
190
|
+
.filter((s) => !seen.has(s.name) && seen.add(s.name) && !skip?.has(s.name))
|
|
191
191
|
.slice(0, MAX_HINTS);
|
|
192
192
|
if (!hits.length) return null;
|
|
193
193
|
const safe = (v) => v.replace(/[\u0000-\u001f\u007f-\u009f]/g, '');
|
|
194
194
|
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
195
|
const n = staleCount(table, fs);
|
|
196
196
|
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 };
|
|
197
|
+
return { out, count: hits.length, names: hits.map((s) => s.name) };
|
|
198
198
|
}
|
|
199
199
|
|
|
200
200
|
export const route = (prompt, table, opts) => pick(prompt, table, opts)?.out ?? null;
|
|
@@ -250,26 +250,70 @@ const userClaudeHook = (udir) => {
|
|
|
250
250
|
} catch { return false; }
|
|
251
251
|
};
|
|
252
252
|
|
|
253
|
+
// Skills already named in a session, one name per line, so a resumed or repeated prompt does not hint (and the agent
|
|
254
|
+
// does not re-read) them again. An id that is not a plain token gets no memory: it is never used as a file name.
|
|
255
|
+
function sessionFile(udir, tool, sid) {
|
|
256
|
+
return typeof sid === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(sid) ? join(udir, 'sessions', `${tool || 'any'}-${sid}`) : null;
|
|
257
|
+
}
|
|
258
|
+
const remembered = (file) => {
|
|
259
|
+
try { return new Set(readFileSync(file, 'utf8').split('\n').filter(Boolean)); } catch { return null; }
|
|
260
|
+
};
|
|
261
|
+
function remember(file, names) {
|
|
262
|
+
if (!file) return;
|
|
263
|
+
try {
|
|
264
|
+
const dir = dirname(file);
|
|
265
|
+
if (!existsSync(file)) {
|
|
266
|
+
mkdirSync(dir, { recursive: true });
|
|
267
|
+
// shortcut: prune old sessions only when a new one starts; fine for a few hundred sessions a week.
|
|
268
|
+
for (const f of readdirSync(dir)) if ((FS.mtime(join(dir, f)) ?? Infinity) < Date.now() - 7 * 864e5) unlinkSync(join(dir, f));
|
|
269
|
+
}
|
|
270
|
+
appendFileSync(file, names.map((n) => `${n}\n`).join(''));
|
|
271
|
+
} catch { /* a read-only sandbox only loses the memory */ }
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
const loadTable = (udir, base) => merge(load(join(udir, 'routes.json')), resolveProject(load(join(base, '.skill-autoroute', 'routes.json')), base));
|
|
275
|
+
|
|
276
|
+
// `route.mjs [tool] suggest <session|-> <text...>`: the agent asks for skills in the middle of its work.
|
|
277
|
+
function suggest(udir, args, i) {
|
|
278
|
+
const tool = i === 1 ? args[0] : undefined;
|
|
279
|
+
const base = process.env.CLAUDE_PROJECT_DIR || process.cwd();
|
|
280
|
+
const table = loadTable(udir, base);
|
|
281
|
+
const hit = table && pick(args.slice(i + 2).join(' '), table, { tool, base });
|
|
282
|
+
process.stdout.write(`${hit ? hit.out : 'No skill fits.'}\n`);
|
|
283
|
+
if (hit) remember(sessionFile(udir, tool, args[i + 1]), hit.names);
|
|
284
|
+
}
|
|
285
|
+
|
|
253
286
|
function main(self) {
|
|
254
287
|
if (process.env.SKILL_AUTOROUTE_DISABLE === '1') return;
|
|
255
288
|
const udir = join(homedir(), '.config', 'skill-autoroute');
|
|
289
|
+
const args = process.argv.slice(2);
|
|
290
|
+
const at = args.indexOf('suggest');
|
|
291
|
+
if (at === 0 || at === 1) return suggest(udir, args, at);
|
|
256
292
|
// The user Claude hook already merges the project table; the project copy beside it would hint twice.
|
|
257
293
|
// Only a Claude user hook counts: a Codex-only user install must not silence the Claude project hook.
|
|
258
294
|
if (self.endsWith(`${sep}.skill-autoroute${sep}route.mjs`) && userClaudeHook(udir)) return;
|
|
259
295
|
try {
|
|
260
|
-
const { prompt } = JSON.parse(readFileSync(0, 'utf8'));
|
|
296
|
+
const { prompt, session_id: sid } = JSON.parse(readFileSync(0, 'utf8'));
|
|
261
297
|
if (typeof prompt !== 'string') return;
|
|
262
298
|
const base = process.env.CLAUDE_PROJECT_DIR || process.cwd();
|
|
263
|
-
const table =
|
|
299
|
+
const table = loadTable(udir, base);
|
|
264
300
|
if (!table) return;
|
|
265
|
-
const
|
|
266
|
-
|
|
267
|
-
const
|
|
301
|
+
const tool = args[0];
|
|
302
|
+
const file = sessionFile(udir, tool, sid);
|
|
303
|
+
const known = file && remembered(file);
|
|
304
|
+
const hit = pick(prompt, table, { tool, base, skip: known ?? undefined });
|
|
305
|
+
// Told once per session: later prompts and resumed rounds already have this line in context.
|
|
306
|
+
const tell = file && !known
|
|
307
|
+
? `To find skills for a new sub-task later in this session, run: node ${JSON.stringify(self)}${tool ? ` ${tool}` : ''} suggest ${sid} "<what you will do next>"`
|
|
308
|
+
: '';
|
|
309
|
+
if (!hit && !tell) return;
|
|
310
|
+
remember(file, hit ? hit.names : []);
|
|
311
|
+
const ctx = [hit?.out, tell].filter(Boolean).join('\n');
|
|
268
312
|
process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } }) + '\n');
|
|
269
313
|
if (process.env.SKILL_AUTOROUTE_LOG === '1' || table.log === true) {
|
|
270
314
|
try {
|
|
271
315
|
mkdirSync(udir, { recursive: true });
|
|
272
|
-
appendFileSync(join(udir, 'usage.log'), `${new Date().toISOString()}\t${hit
|
|
316
|
+
appendFileSync(join(udir, 'usage.log'), `${new Date().toISOString()}\t${hit?.count ?? 0}\t${ctx.length}\n`);
|
|
273
317
|
} catch { /* logging must never break a prompt */ }
|
|
274
318
|
}
|
|
275
319
|
} catch (e) {
|
package/package.json
CHANGED
package/src/flow.js
CHANGED
|
@@ -410,6 +410,24 @@ export function setSkill(o, ui, name, state) {
|
|
|
410
410
|
if (state === 'on' && hits.some((s) => !s.patterns?.length)) ui.log(`${show(name)} has no trigger rules yet, so it gets no hints. Run: npx skill-autoroute regenerate`);
|
|
411
411
|
}
|
|
412
412
|
|
|
413
|
+
export function list(o, ui) {
|
|
414
|
+
const path = routesPath(scopeOf(o));
|
|
415
|
+
const table = readTable(path);
|
|
416
|
+
if (!table) return ui.log(`no table at ${show(path)}; run install first`);
|
|
417
|
+
const skills = table.skills.filter((s) => s && (!o.tools?.length || o.tools.some((t) => (s.tools ?? [s.tool]).includes(t))));
|
|
418
|
+
if (!skills.length) return ui.log('No skills in this scope for the selected tools.');
|
|
419
|
+
ui.log('Routing configuration (on = enabled for matching prompts; not proof of invocation).\nRules are case-insensitive: AND within a rule, OR between rules. Own words also trigger a match.');
|
|
420
|
+
for (const s of skills) {
|
|
421
|
+
ui.log(`${show(s.name)} ${s.enabled ? 'on' : 'off'} ${(s.tools ?? [s.tool]).map(show).join(', ')} priority ${show(s.priority ?? 50)}`);
|
|
422
|
+
if (s.path) ui.log(` Path: ${show(s.path)}`);
|
|
423
|
+
if (s.projects?.length) ui.log(` Projects: ${s.projects.map(show).join(', ')}`);
|
|
424
|
+
ui.log(s.patterns?.length
|
|
425
|
+
? ` Rules: ${s.patterns.map((rule) => `(${rule.map(show).join(' AND ')})`).join(' OR ')}`
|
|
426
|
+
: ' No trigger rules.');
|
|
427
|
+
if (s.words?.length) ui.log(` Own words: ${s.words.map(show).join(', ')}`);
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
|
|
413
431
|
export function status(o, ui) {
|
|
414
432
|
const scope = scopeOf(o);
|
|
415
433
|
for (const t of findTools()) ui.log(`${t.name}: CLI ${t.cli ? 'found' : 'not found'}, config ${t.configDir ? 'found' : 'not found'}, ${ADAPTERS[t.name].hasHook(scope) ? 'hook installed' : 'no hook'}`);
|