skills-atlas-cli 0.3.0 → 0.4.0

package/README.md

@@ -47,6 +47,7 @@ skills-atlas info brainstorming
 skills-atlas install brainstorming             # → ~/.claude/skills/   (default, all projects)
 skills-atlas install brainstorming --project   # → ./.claude/skills/   (this project only)
 skills-atlas install brainstorming --chain     # install the whole ⛓ workflow it belongs to
+skills-atlas use brainstorming                 # install AND activate now — prints SKILL.md, no restart
 skills-atlas install brainstorming --dry-run   # preview the files, write nothing
 
 # 🗂️ Manage what you've installed   (like a package manager)
@@ -103,6 +104,25 @@ 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 **strongly
+matches** a catalog skill you don't have, Claude gets a one-line note and can
+offer to install + activate it — you don't have to know the skill exists. It's:
+
+- **off by default** — you turn it on explicitly; `hook off` removes it cleanly.
+- **quiet** — only fires on a confident match, never for an already-installed
+  skill, never the same skill twice, with a cooldown between suggestions, and
+  **Claude still decides** whether it's relevant enough to mention.
+- **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,11 +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;
-const commands = { search, info, install, installed, upgrade, remove, outdated, doctor, update, categories, list };
+// `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, suggest, hook, update, categories, list };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -23,6 +27,7 @@ find & install:
   search <query>     find skills (filters: -c category, -p persona, -t type, --chain)
   info <skill>       show description, usage guidance, sources & install command
   install <skill>    download into .claude/skills/ (--chain for the whole workflow)
+  use <skill>        install AND activate it for the current session now (inline)
 
 manage what you've installed:
   installed          list installed skills (global + project)
@@ -31,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.0",
+  "version": "0.4.0",
   "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/args.js

@@ -20,6 +20,7 @@ const ALL = {
   en: { type: 'boolean' },
   zh: { type: 'boolean' },
   all: { type: 'boolean' },
+  inline: { type: 'boolean' },
   help: { type: 'boolean', short: 'h' },
 };
 

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/install.js

@@ -1,7 +1,12 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const { parse } = require('../args');
+
+const readSkillMd = dest => {
+  try { return fs.readFileSync(path.join(dest, 'SKILL.md'), 'utf8'); } catch { return null; }
+};
 const { loadData } = require('../data');
 const { buildIndices, vendorsFor, suggestSkills, skillDocPath } = require('../index-build');
 const { listSkillFiles } = require('../github');
@@ -81,7 +86,7 @@ async function installChain({ row, vendor, src, targetRoot, values }) {
 
 module.exports = async function install(argv) {
   const { values, positionals } = parse(argv,
-    ['global', 'project', 'source', 'force', 'yes', 'chain', 'dry-run', 'json']);
+    ['global', 'project', 'source', 'force', 'yes', 'chain', 'inline', 'dry-run', 'json']);
   if (values.help) { console.log(HELP); return; }
 
   const name = positionals[0];
@@ -241,10 +246,12 @@ module.exports = async function install(argv) {
   }
 
   if (values.json) {
-    console.log(JSON.stringify({
+    const out = {
       skill, mode: 'folder', source: src.name,
       dest: result.dest, files: result.fileCount, scripts: result.scripts.length, branch: result.branchUsed,
-    }));
+    };
+    if (values.inline) out.skillMd = readSkillMd(result.dest);
+    console.log(JSON.stringify(out));
     return;
   }
 
@@ -264,5 +271,16 @@ module.exports = async function install(argv) {
     ? infoForRow(skill, chosen.row, data.vendors)
     : buildInfo(skill, { skillIndex: idx.skillIndex, vendors: data.vendors });
   console.log(renderInfo(guide, { en: !values.zh, all: true }));
-  console.log(dim('\nStart a new Claude Code session to load the skill, then invoke it by name.'));
+
+  if (values.inline) {
+    const body = readSkillMd(result.dest);
+    if (body) {
+      console.log('\n' + dim('─── SKILL.md (active for this task — follow it now) ───'));
+      console.log(body.trim());
+      console.log(dim('─── end SKILL.md ───'));
+    }
+    console.log(dim('\n(the folder is also installed for future sessions)'));
+  } else {
+    console.log(dim('\nStart a new Claude Code session to load the skill, then invoke it by name.'));
+  }
 };

package/src/commands/suggest.js

@@ -0,0 +1,78 @@
+// `skills-atlas suggest` — the autopilot. Runs as a Claude Code UserPromptSubmit
+// hook: reads the event JSON from stdin, matches the prompt against the catalog
+// locally, and (if a strong, fresh, not-installed match survives a cooldown)
+// emits a one-line additionalContext for Claude to weigh. 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 { pickSuggestion } = 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 pick = pickSuggestion(flatRows, prompt, { installed, suggested });
+    if (!pick) { writeState(file, state); return; }
+
+    const uc = pick.row.use_case_en || pick.row.use_case || '';
+    const ctx =
+      `[Skills Atlas autopilot] The user's task may fit the installable agent skill ` +
+      `\`${pick.skill}\`${uc ? ` (catalog use-case: "${uc}")` : ''}. ONLY if it's clearly ` +
+      `relevant to what they actually asked, briefly offer it — they can install and ` +
+      `activate it now with \`skills-atlas use ${pick.skill} --yes\`. If it isn't a strong ` +
+      `fit, don't mention it.`;
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } }));
+
+    state.lastSuggestedCount = state.count;
+    state.suggested = [...suggested, pick.skill];
+    writeState(file, state);
+  } catch {
+    // fail-open: never break the user's workflow
+  }
+};

package/src/search-core.js

@@ -154,4 +154,43 @@ function searchRows(rows, opts = {}) {
   return runSearch(rows, opts).rows;
 }
 
-module.exports = { tokenize, searchRows, runSearch, scoreRow, buildFields, maxStars, PERSONA_ALIAS };
+// Autopilot: pick the single best skill to proactively suggest for a free-text
+// prompt, or null. Conservative on purpose — requires a STRONG, multi-signal
+// match (an exact skill-name token, OR ≥2 distinct query tokens hitting the
+// high-signal fields name/group/use_case), so a single common word can't
+// trigger it. Skips already-installed and already-suggested skills.
+function pickSuggestion(rows, prompt, { installed = new Set(), suggested = new Set() } = {}) {
+  const tokens = tokenize(lc(prompt));
+  if (tokens.length < 2) return null; // too vague to suggest confidently
+  const inName = (name, ts) => { const n = lc(name); return ts.filter(t => n.includes(t)).length; };
+
+  let best = null;
+  for (const r of rows) {
+    const f = buildFields(r);
+    const skillSet = new Set((r.skills || []).map(lc));
+    let nameHits = 0, otherHits = 0, exact = false;
+    for (const t of tokens) {
+      if (skillSet.has(t)) exact = true;
+      if (fieldHas(f.name, t)) nameHits++;          // skill-name match = strongest signal
+      else if (fieldHas(f.group, t) || fieldHas(f.use, t)) otherHits++;
+    }
+    // Require a skill-NAME signal (or an exact name token). Two ordinary words
+    // co-occurring in some row's verbose prose is NOT enough — that's the noise.
+    if (!exact && !(nameHits >= 1 && nameHits + otherHits >= 2)) continue;
+    const score = nameHits * 15 + otherHits * 6 + (exact ? 50 : 0) + maxStars(r) / 1e7;
+    if (!best || score > best.score) best = { row: r, score };
+  }
+  if (!best) return null;
+
+  // pick the most on-point skill in the winning row that isn't already in play
+  const cand = (best.row.skills || []).filter(s => !installed.has(s) && !suggested.has(s));
+  if (!cand.length) return null;
+  cand.sort((a, b) => inName(b, tokens) - inName(a, tokens));
+  // the suggested skill's own name must overlap the prompt, else it's a mispick
+  if (inName(cand[0], tokens) === 0) return null;
+  return { skill: cand[0], row: best.row };
+}
+
+module.exports = {
+  tokenize, searchRows, runSearch, scoreRow, buildFields, maxStars, pickSuggestion, PERSONA_ALIAS,
+};