skills-atlas-cli 0.4.0 → 0.4.2

package/README.md

@@ -110,14 +110,21 @@ just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
 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:
+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, explains **what it does and why it fits your task**, then offers a choice:
+use it now, see what it covers first (`skills-atlas info`), or skip. 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 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.
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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

@@ -69,7 +69,13 @@ module.exports = async function hook(argv) {
   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'));
+    console.log('\nHow it works: when what you ask lines up with a skill you don\'t have yet, Claude');
+    console.log('quietly gets a shortlist and — only if one truly fits — explains it and offers a choice:');
+    console.log(dim('  you:    "run a pre-mortem before we launch"'));
+    console.log(dim('  claude: "that\'s exactly what the pre-mortem skill does — it stress-tests your plan'));
+    console.log(dim('           before launch. use it now / see what it covers / skip?"'));
+    console.log(dim('\nIt stays silent on greetings and generic asks, never repeats a skill, and Claude makes'));
+    console.log(dim('the final call on relevance. Nothing leaves your machine.'));
+    console.log(dim('\nneeds `skills-atlas` on PATH (npm i -g skills-atlas-cli).  turn off: skills-atlas hook off'));
   }
 };

package/src/commands/install.js

@@ -275,12 +275,16 @@ module.exports = async function install(argv) {
   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('\n' + dim('─── SKILL.md — the skill\'s own instructions; apply them to the task now ───'));
       console.log(body.trim());
       console.log(dim('─── end SKILL.md ───'));
     }
-    console.log(dim('\n(the folder is also installed for future sessions)'));
+    console.log(`\n${green('✓')} ${bold(skill)} is now active — use the instructions above for the task at hand.`);
+    console.log(dim(`  installed at ${fsu.tildify(result.dest)} (auto-loads in new sessions) · what it does: skills-atlas info ${skill} · remove: skills-atlas remove ${skill}`));
   } else {
-    console.log(dim('\nStart a new Claude Code session to load the skill, then invoke it by name.'));
+    console.log(`\n${bold(skill)} is installed but not loaded yet. To use it:`);
+    console.log(dim(`  • now, in this session:  skills-atlas use ${skill}`));
+    console.log(dim('  • or start a new Claude Code session — it auto-loads from ~/.claude/skills/'));
+    console.log(dim(`  what it does: skills-atlas info ${skill} · remove: skills-atlas remove ${skill}`));
   }
 };

package/src/commands/suggest.js

@@ -1,9 +1,10 @@
 // `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.
+// 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');
@@ -11,7 +12,7 @@ const os = require('os');
 const path = require('path');
 const { loadData } = require('../data');
 const { buildIndices } = require('../index-build');
-const { pickSuggestion } = require('../search-core');
+const { suggestCandidates } = require('../search-core');
 const manifest = require('../manifest');
 const fsu = require('../fsutil');
 
@@ -57,20 +58,28 @@ module.exports = async function suggest() {
     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 { fire, candidates } = suggestCandidates(flatRows, prompt, { installed, suggested });
+    if (!fire) { writeState(file, state); return; }
 
-    const uc = pick.row.use_case_en || pick.row.use_case || '';
+    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}` : ''}  (details: \`skills-atlas info ${c.skill}\` · use now: \`skills-atlas use ${c.skill} --yes\`)`;
+    }).join('\n');
     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.`;
+      `[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 genuinely fits, DON'T just name it: in one line tell the user what it does and why it ` +
+      `fits THIS task (it's a curated skill from the Skills Atlas catalog, not something you made up), ` +
+      `then let them choose — activate it now (\`skills-atlas use <skill> --yes\` installs + applies it ` +
+      `immediately), see what it covers first (\`skills-atlas info <skill>\`), or skip and you'll just ` +
+      `do the task yourself. 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 — don't 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, pick.skill];
+    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,43 +154,118 @@ function searchRows(rows, opts = {}) {
   return runSearch(rows, opts).rows;
 }
 
-// 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() } = {}) {
+// 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 null; // too vague to suggest confidently
-  const inName = (name, ts) => { const n = lc(name); return ts.filter(t => n.includes(t)).length; };
+  if (tokens.length < 2) return { fire: false, candidates: [], weak: false };
+  const taken = new Set([...installed, ...suggested]);
+  const info = segmentDf(rows);
 
-  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;
+  // 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) {
-      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++;
+      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);
     }
-    // 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 (strong) anchors.push({ skill: s, row: r, weight, strong });
   }
-  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 };
+  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, pickSuggestion, PERSONA_ALIAS,
+  tokenize, searchRows, runSearch, scoreRow, buildFields, maxStars,
+  nameWordHit, matchedSegment, suggestCandidates, PERSONA_ALIAS,
 };