skills-atlas-cli 0.3.1 → 0.4.1

package/README.md

@@ -104,6 +104,31 @@ just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
 /plugin install skills-atlas@skills-atlas
 ```
 
+## Autopilot (opt-in) — the right skill finds you
+
+```bash
+skills-atlas hook on      # enable    (skills-atlas hook off / status)
+```
+
+Registers a Claude Code `UserPromptSubmit` hook. When what you ask matches the
+territory of a catalog skill you don't have, the hook hands Claude a short
+shortlist of candidates and **Claude decides** whether any genuinely fits — and
+if so offers to install + activate it. You don't have to know the skill exists.
+The split is deliberate: the hook does **recall** (a distinctive-word match
+against the catalog, so the right skill is on the table), Claude does
+**precision** (it understands your intent and stays silent unless one truly
+fits, or searches further itself). It's:
+
+- **off by default** — you turn it on explicitly; `hook off` removes it cleanly.
+- **quiet** — only fires on a distinctive match (greetings and generic actions
+  like "fix the typo" stay silent), never for an already-installed skill, never
+  the same skill twice, with a cooldown between suggestions — and Claude is the
+  final filter on relevance.
+- **local & private** — your prompt is matched against the bundled catalog
+  on your machine; nothing is sent anywhere.
+- **safe** — never auto-installs (always your call), and fails open (a hook
+  error never blocks your prompt).
+
 ## License
 
 MIT. Each installed skill keeps its own source repository's license.

package/bin/skills.js

@@ -9,13 +9,15 @@ const upgrade = require('../src/commands/upgrade');
 const remove = require('../src/commands/remove');
 const outdated = require('../src/commands/outdated');
 const doctor = require('../src/commands/doctor');
+const suggest = require('../src/commands/suggest');
+const hook = require('../src/commands/hook');
 const update = require('../src/commands/update');
 const { categories, list } = require('../src/commands/categories');
 
 const VERSION = require('../package.json').version;
 // `use` = install + activate inline (emit the SKILL.md so an agent follows it now).
 const use = argv => install([...argv, '--inline']);
-const commands = { search, info, install, use, installed, upgrade, remove, outdated, doctor, update, categories, list };
+const commands = { search, info, install, use, installed, upgrade, remove, outdated, doctor, suggest, hook, update, categories, list };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -34,6 +36,9 @@ manage what you've installed:
   remove <skill>     delete an installed skill
   doctor             health check: orphans, drift, missing SKILL.md, license/script risks
 
+autopilot (opt-in):
+  hook on|off|status proactively suggest a skill in Claude when your prompt fits one
+
 catalog:
   update             refresh the catalog from the public data feed
   categories         list the top-level categories

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Search, install and learn AI agent skills from the terminal — powered by the Skills Atlas catalog.",
   "bin": {
     "skills-atlas": "bin/skills.js",

package/src/commands/hook.js

@@ -0,0 +1,75 @@
+// `skills-atlas hook on|off|status` — opt-in switch for the autopilot. Registers
+// (or removes) a UserPromptSubmit hook in ~/.claude/settings.json that runs
+// `skills-atlas suggest`. Merge-safe (never clobbers other settings), idempotent,
+// backs up before writing, removes only our own entry.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { parse } = require('../args');
+const { green, dim } = require('../format');
+
+const HOOK_CMD = 'skills-atlas suggest';
+const settingsPath = () => path.join(os.homedir(), '.claude', 'settings.json');
+
+function readSettings(p) {
+  if (!fs.existsSync(p)) return {};
+  return JSON.parse(fs.readFileSync(p, 'utf8')); // may throw → caller handles
+}
+const isOurs = e => e && Array.isArray(e.hooks)
+  && e.hooks.some(h => h && typeof h.command === 'string' && h.command.includes(HOOK_CMD));
+
+module.exports = async function hook(argv) {
+  const { values, positionals } = parse(argv, ['json']);
+  if (values.help) { console.log('usage: skills-atlas hook <on|off|status>'); return; }
+  const sub = positionals[0] || 'status';
+  const p = settingsPath();
+
+  if (sub === 'status') {
+    let on = false;
+    try { on = ((readSettings(p).hooks || {}).UserPromptSubmit || []).some(isOurs); } catch { /* invalid → off */ }
+    if (values.json) { console.log(JSON.stringify({ enabled: on, settings: p })); return; }
+    console.log(`autopilot: ${on ? green('on') : dim('off')}   ${dim(p)}`);
+    if (!on) console.log(dim('enable: skills-atlas hook on'));
+    return;
+  }
+
+  if (sub !== 'on' && sub !== 'off') {
+    console.error('usage: skills-atlas hook <on|off|status>');
+    process.exitCode = 1;
+    return;
+  }
+
+  let settings;
+  try { settings = readSettings(p); }
+  catch (e) { console.error(`${p} is not valid JSON — fix it first (${e.message}).`); process.exitCode = 1; return; }
+
+  // Coerce defensively: a user's settings could have `hooks` as a non-object or
+  // `UserPromptSubmit` as a non-array. Don't crash on it — start from a clean shape.
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) settings.hooks = {};
+  const arr = Array.isArray(settings.hooks.UserPromptSubmit) ? settings.hooks.UserPromptSubmit : [];
+
+  if (sub === 'on') {
+    if (arr.some(isOurs)) { console.log(dim('autopilot already on.')); return; }
+    settings.hooks.UserPromptSubmit = [...arr, { matcher: '*', hooks: [{ type: 'command', command: HOOK_CMD, timeout: 5 }] }];
+  } else {
+    const kept = arr.filter(e => !isOurs(e));
+    if (kept.length) settings.hooks.UserPromptSubmit = kept;
+    else delete settings.hooks.UserPromptSubmit;
+    if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    if (fs.existsSync(p) && !fs.existsSync(`${p}.bak`)) fs.copyFileSync(p, `${p}.bak`); // keep the pristine original
+    fs.writeFileSync(p, JSON.stringify(settings, null, 2) + '\n');
+  } catch (e) { console.error(`failed to write ${p}: ${e.message}`); process.exitCode = 1; return; }
+
+  if (values.json) { console.log(JSON.stringify({ enabled: sub === 'on', settings: p })); return; }
+  console.log(`${green('✓')} autopilot ${sub === 'on' ? 'enabled' : 'disabled'}  ${dim(p)}`);
+  if (sub === 'on') {
+    console.log(dim('Claude now gets a one-line skill suggestion when your prompt strongly matches a catalog skill.'));
+    console.log(dim('needs `skills-atlas` on PATH (npm i -g skills-atlas-cli). turn off: skills-atlas hook off'));
+  }
+};

package/src/commands/suggest.js

@@ -0,0 +1,84 @@
+// `skills-atlas suggest` — the autopilot. Runs as a Claude Code UserPromptSubmit
+// hook: reads the event JSON from stdin, retrieves a SHORTLIST of catalog skills
+// that may fit the prompt (recall), and injects them as additionalContext for
+// Claude to judge (precision) — Claude offers one only if it genuinely fits, and
+// can run `skills-atlas search` itself to look further. ALWAYS exits 0 and never
+// blocks the user (fail-open). Matching is local-only — the prompt is never sent
+// anywhere.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { loadData } = require('../data');
+const { buildIndices } = require('../index-build');
+const { suggestCandidates } = require('../search-core');
+const manifest = require('../manifest');
+const fsu = require('../fsutil');
+
+const COOLDOWN = 3; // min prompts between suggestions
+
+function stateFile(sessionId) {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  const id = String(sessionId || 'nosession').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 80);
+  return path.join(base, 'skills-atlas', 'suggest', `${id}.json`);
+}
+function readState(f) {
+  try { return JSON.parse(fs.readFileSync(f, 'utf8')); }
+  catch { return { count: 0, lastSuggestedCount: -COOLDOWN, suggested: [] }; }
+}
+function writeState(f, s) {
+  try { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, JSON.stringify(s)); } catch { /* ignore */ }
+}
+
+module.exports = async function suggest() {
+  try {
+    if (process.stdin.isTTY) {
+      console.error('skills-atlas suggest is a UserPromptSubmit hook (reads the event JSON from stdin).');
+      console.error('enable the autopilot with:  skills-atlas hook on');
+      return;
+    }
+
+    let event = {};
+    try { event = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { /* not JSON → bail */ }
+    const prompt = event.prompt || '';
+    if (!prompt || prompt.length < 8) return;
+
+    const file = stateFile(event.session_id || event.sessionId);
+    const state = readState(file);
+    state.count = (state.count || 0) + 1;
+
+    // cooldown — don't suggest on every prompt
+    if (state.count - (state.lastSuggestedCount ?? -COOLDOWN) < COOLDOWN) { writeState(file, state); return; }
+
+    const { data } = loadData({ quiet: true });
+    const { flatRows } = buildIndices(data);
+
+    const installed = new Set();
+    for (const s of fsu.scopesFor({})) for (const e of manifest.list(s.root)) installed.add(e.skill);
+    const suggested = new Set(state.suggested || []);
+
+    const { fire, candidates } = suggestCandidates(flatRows, prompt, { installed, suggested });
+    if (!fire) { writeState(file, state); return; }
+
+    const lines = candidates.map(c => {
+      const uc = (c.row.use_case_en || c.row.use_case || '').replace(/\s+/g, ' ').trim().slice(0, 80);
+      return `- ${c.skill}${uc ? ` — ${uc}` : ''}  (install+activate: \`skills-atlas use ${c.skill} --yes\`)`;
+    }).join('\n');
+    const ctx =
+      `[Skills Atlas autopilot] The user may be doing something one of these installable agent ` +
+      `skills is built for. Judge for yourself — do NOT mention any of this unless one of them ` +
+      `genuinely fits what they actually asked:\n${lines}\n` +
+      `If one clearly fits, briefly offer it and (with the user's ok) install it via its command. ` +
+      `If none fit but the task plainly needs a specialized skill, you may run ` +
+      `\`skills-atlas search "<short intent>"\` to look further. If nothing fits, say nothing about ` +
+      `this at all — do not mention this hook, these skills, or that a suggestion was made.`;
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } }));
+
+    state.lastSuggestedCount = state.count;
+    state.suggested = [...suggested, ...candidates.map(c => c.skill)];
+    writeState(file, state);
+  } catch {
+    // fail-open: never break the user's workflow
+  }
+};

package/src/search-core.js

@@ -154,4 +154,118 @@ function searchRows(rows, opts = {}) {
   return runSearch(rows, opts).rows;
 }
 
-module.exports = { tokenize, searchRows, runSearch, scoreRow, buildFields, maxStars, PERSONA_ALIAS };
+// Generic words that, on their OWN, must not make the autopilot fire: common
+// English verbs/nouns that often appear inside skill names but carry no domain
+// intent ("fix the typo", "build the app", "design a system" → stay quiet). They
+// can still ride along in a multi-word match; they just can't trigger alone.
+const ANCHOR_STOP = new Set([
+  'fix', 'make', 'build', 'create', 'add', 'remove', 'delete', 'update', 'change',
+  'changes', 'set', 'run', 'clean', 'rename', 'move', 'copy', 'write', 'review',
+  'improve', 'optimize', 'check', 'format', 'handle', 'manage', 'generate', 'edit',
+  'open', 'start', 'stop', 'ship', 'render', 'page', 'file', 'files', 'line', 'load',
+  'code', 'app', 'apps', 'work', 'thing', 'things', 'stuff', 'data', 'system',
+  'design', 'document', 'component', 'components', 'feature', 'features', 'variable',
+  'function', 'project', 'task', 'tool', 'name', 'names',
+]);
+
+// Word-aware skill-NAME match: return the matched name segment (or null). Stricter
+// than substring — generic fragments must NOT match inside a name ("line" ≠
+// "guide-LINE-s"). Stem matching only for tokens/segments ≥5 chars so
+// "debug"~"debugging" matches but "line"~"linear" does not. Plural-tolerant.
+function matchedSegment(skillName, token) {
+  const segs = lc(skillName).split(/[^a-z0-9]+/).filter(Boolean);
+  let hit = null;
+  for (const seg of segs) {
+    if (seg === token) return seg;                                  // exact wins
+    if ((token.length >= 5 && seg.startsWith(token)) ||             // debug → debugging
+        (seg.length >= 5 && token.startsWith(seg)) ||               // requesting ← request
+        (token.length > 3 && token.endsWith('s') && seg === token.slice(0, -1)) || // tests → test
+        (seg.length > 3 && seg.endsWith('s') && token === seg.slice(0, -1))) hit = seg; // test → tests
+  }
+  return hit;
+}
+const nameWordHit = (skillName, token) => matchedSegment(skillName, token) !== null;
+
+// Document frequency of each name segment across all skills (memoized per rows
+// array). Distinctive segments ("brainstorm", "mortem", "figma") appear in few
+// skills → high IDF; generic ones ("user", "test") in many → low IDF.
+const _dfCache = new WeakMap();
+function segmentDf(rows) {
+  let info = _dfCache.get(rows);
+  if (info) return info;
+  const df = new Map();
+  let n = 0;
+  for (const r of rows) for (const s of r.skills || []) {
+    n++;
+    for (const seg of new Set(lc(s).split(/[^a-z0-9]+/).filter(Boolean))) df.set(seg, (df.get(seg) || 0) + 1);
+  }
+  info = { df, n: n || 1 };
+  _dfCache.set(rows, info);
+  return info;
+}
+const idfOf = (info, seg) => Math.log(1 + info.n / ((info.df.get(seg) || 0) + 1));
+
+const FIRE_IDF = 4.2; // a single distinctive name word must clear this to fire alone
+
+// Autopilot recall: collect a SHORTLIST of catalog skills that may fit a free-text
+// prompt, for Claude to judge (we do recall; Claude does precision). Returns
+// { fire, candidates: [{skill, row}], weak }. Sources, in order:
+//   1. skill-NAME matches, scored by summed IDF of the matched words and sorted
+//      so the most distinctive multi-word match leads (paper-slide-deck beats a
+//      one-word "research" match), then
+//   2. the general ranked search (runSearch) fills remaining slots.
+// `fire` is true only when there's a distinctive anchor (a rare name word, or ≥2
+// matched name words) or an otherwise strong (non-weak) match — so the hook stays
+// quiet on greetings and generic dev actions ("fix the typo", "build the app").
+function suggestCandidates(rows, prompt, { installed = new Set(), suggested = new Set(), limit = 5 } = {}) {
+  const tokens = tokenize(lc(prompt));
+  if (tokens.length < 2) return { fire: false, candidates: [], weak: false };
+  const taken = new Set([...installed, ...suggested]);
+  const info = segmentDf(rows);
+
+  // 1. name anchors — ONLY contentful (non-generic) name words count, weighted by
+  // distinctiveness. A skill matched purely by a generic word ("optimize",
+  // "design", "system") is not an anchor at all, so generic words can neither
+  // fire the hook nor crowd the shortlist.
+  const anchors = [];
+  for (const r of rows) for (const s of r.skills || []) {
+    if (taken.has(s)) continue;
+    let weight = 0, strong = 0;
+    const usedSeg = new Set();
+    for (const t of tokens) {
+      const seg = matchedSegment(s, t);
+      if (!seg || usedSeg.has(seg)) continue;
+      usedSeg.add(seg);
+      if (ANCHOR_STOP.has(t) || ANCHOR_STOP.has(seg)) continue; // generic word — ignore
+      strong++;
+      weight += idfOf(info, seg);
+    }
+    if (strong) anchors.push({ skill: s, row: r, weight, strong });
+  }
+  anchors.sort((a, b) => b.weight - a.weight || maxStars(b.row) - maxStars(a.row));
+
+  const out = [];
+  const seen = new Set(taken);
+  const push = (skill, row) => { if (!seen.has(skill)) { seen.add(skill); out.push({ skill, row }); } };
+  for (const a of anchors) { if (out.length >= limit) break; push(a.skill, a.row); }
+
+  // 2. fill from the general ranked search (one primary skill per row)
+  const { rows: ranked, weak } = runSearch(rows, { query: prompt });
+  for (const r of ranked) {
+    if (out.length >= limit) break;
+    const s = (r.skills || []).find(x => !seen.has(x));
+    if (s) push(s, r);
+  }
+
+  // fire decision: only on a real name anchor — two contentful name words, OR one
+  // distinctive (high-IDF) one. A prompt with mere prose overlap and no name
+  // signal stays silent (better a miss than noise on every generic prompt); the
+  // ranked search still ENRICHES the shortlist once an anchor has fired.
+  const fire = out.length > 0 && anchors.some(a => a.strong >= 2 || a.weight >= FIRE_IDF);
+  return { fire, candidates: out.slice(0, limit), weak };
+}
+
+module.exports = {
+  tokenize, searchRows, runSearch, scoreRow, buildFields, maxStars,
+  nameWordHit, matchedSegment, suggestCandidates, PERSONA_ALIAS,
+};