skills-atlas-cli 0.8.5 → 0.8.8

package/bin/skills.js

@@ -15,6 +15,7 @@ const registry = require('../src/commands/registry');
 const suggest = require('../src/commands/suggest');
 const hook = require('../src/commands/hook');
 const gaps = require('../src/commands/gaps');
+const prune = require('../src/commands/prune');
 const update = require('../src/commands/update');
 const mcp = require('../src/commands/mcp');
 const { categories, list } = require('../src/commands/categories');
@@ -22,7 +23,7 @@ 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, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, update, categories, list, registry, mcp };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, prune, update, categories, list, registry, mcp };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -46,6 +47,7 @@ manage what you've installed:
 autopilot (opt-in):
   hook on|off|status proactively suggest a skill in Claude when your prompt fits one
   gaps               kinds of work you keep doing without a skill (run: skills-atlas hook on)
+  prune              installed skills you no longer use — Claude suggests removing them
 
 catalog:
   update             refresh the catalog from the public data feed

package/package.json

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

@@ -23,18 +23,18 @@ const isOurs = e => e && Array.isArray(e.hooks)
 
 module.exports = async function hook(argv) {
   const { values, positionals } = parse(argv, ['json']);
-  if (values.help) { console.log('usage: skills-atlas hook <on|off|status|suggest on|off|gaps on|off>'); return; }
+  if (values.help) { console.log('usage: skills-atlas hook <on|off|status|suggest on|off|gaps on|off|prune on|off>'); return; }
   const sub = positionals[0] || 'status';
   const p = settingsPath();
 
-  if (sub === 'suggest' || sub === 'gaps') {
+  if (sub === 'suggest' || sub === 'gaps' || sub === 'prune') {
     const onoff = positionals[1];
     if (onoff !== 'on' && onoff !== 'off') {
       console.error(`usage: skills-atlas hook ${sub} <on|off>`); process.exitCode = 1; return;
     }
-    const key = sub === 'suggest' ? 'suggest' : 'gapAlerts';
+    const key = sub === 'suggest' ? 'suggest' : sub === 'gaps' ? 'gapAlerts' : 'prune';
     registry.setAutopilot({ [key]: onoff === 'on' });
-    const label = sub === 'suggest' ? 'per-prompt autopilot' : 'gap alerts';
+    const label = sub === 'suggest' ? 'per-prompt autopilot' : sub === 'gaps' ? 'gap alerts' : 'prune suggestions';
     console.log(`${green('✓')} ${label}: ${onoff === 'on' ? green('on') : dim('off')}`);
     return;
   }
@@ -48,11 +48,12 @@ module.exports = async function hook(argv) {
     if (on) {
       console.log(`  per-prompt suggest: ${ap.suggest ? green('on') : dim('off')}   ${dim('(skills-atlas hook suggest on|off)')}`);
       console.log(`  gap alerts:         ${ap.gapAlerts ? green('on') : dim('off')}   ${dim('(skills-atlas hook gaps on|off)')}`);
-      console.log(dim('  review gaps: skills-atlas gaps'));
+      console.log(`  prune suggestions:  ${ap.prune ? green('on') : dim('off')}   ${dim('(skills-atlas hook prune on|off)')}`);
+      console.log(dim('  review: skills-atlas gaps  ·  skills-atlas prune'));
     } else {
       // Hook isn't registered, so these sub-toggles don't do anything yet — don't
       // imply the autopilot is running. Show them dimmed with the caveat.
-      console.log(dim(`  (suggest ${ap.suggest ? 'on' : 'off'}, gap alerts ${ap.gapAlerts ? 'on' : 'off'} — they take effect once you run 'skills-atlas hook on')`));
+      console.log(dim(`  (suggest ${ap.suggest ? 'on' : 'off'}, gap alerts ${ap.gapAlerts ? 'on' : 'off'}, prune ${ap.prune ? 'on' : 'off'} — they take effect once you run 'skills-atlas hook on')`));
       console.log(dim('enable: skills-atlas hook on'));
     }
     return;

package/src/commands/prune.js

@@ -0,0 +1,107 @@
+// `skills-atlas prune` — the inverse of `gaps`. Surface the user's INSTALLED skills
+// (with install age + what each does) plus their recent activity, and a judging
+// instruction, so CLAUDE spots skills that no longer fit the user's work and offers
+// to remove them. We provide the data; Claude judges. NEVER deletes. No network.
+'use strict';
+
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, rowsFor } = require('../index-build');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const transcripts = require('../transcripts');
+const prunestate = require('../prunestate');
+const { dim, green } = require('../format');
+
+const FRESH_DAYS = 14; // never suggest removing something installed this recently
+
+const HELP = `usage: skills-atlas prune [dismiss <skill> | clear]
+
+Surface your installed skills + recent Claude Code activity so Claude can spot ones
+you no longer use and offer to remove them. Run it in Claude Code (or ask Claude
+"any skills I can clean up?"). Never deletes anything — you confirm each removal.
+
+  prune                 review installed skills vs recent activity → Claude suggests
+  prune dismiss <skill> stop suggesting to remove one
+  prune clear           reset dismissals
+  --json`;
+
+// Installed skills (both scopes) worth reviewing: older than FRESH_DAYS and not
+// dismissed, annotated with install age + what each does (from the catalog).
+function reviewList(data, dismissed, now) {
+  const idx = buildIndices(data);
+  const out = [];
+  for (const s of fsu.scopesFor({})) {
+    for (const e of manifest.list(s.root)) {
+      if (dismissed.includes(e.skill)) continue;
+      const ageDays = e.installedAt ? Math.floor((now - Date.parse(e.installedAt)) / 86400000) : null;
+      if (ageDays !== null && ageDays >= 0 && ageDays < FRESH_DAYS) continue; // give new installs time
+      const row = rowsFor(idx.skillIndex, e.skill)[0];
+      out.push({
+        skill: e.skill,
+        scope: s.name,
+        ageDays,
+        use: row ? (row.use_case_en || row.use_case || '') : '',
+      });
+    }
+  }
+  return out;
+}
+
+const instruction = dismissed =>
+  `Each skill above is installed but might no longer fit what the user is doing. From their recent ` +
+  `activity, flag any installed skill whose domain hasn't come up lately and they're unlikely to need ` +
+  `right now: name it, say briefly why it looks unused, and offer to remove it with ` +
+  `\`skills-atlas remove <skill>\` (add --project for a project-scoped one). NEVER remove anything ` +
+  `yourself — always let the user decide.` +
+  (dismissed.length ? ` Already dismissed (skip these): ${dismissed.join(', ')}.` : '') +
+  ` If every installed skill still fits their work, say nothing needs pruning.`;
+
+// The full text block handed to Claude (shared by the command and the hook nudge).
+function digestText(installed, recent, dismissed) {
+  const skills = installed.map(s =>
+    `  - ${s.skill} [${s.scope}]${s.ageDays != null ? ` · installed ${s.ageDays}d ago` : ''}` +
+    `${s.use ? ` · ${s.use.replace(/\s+/g, ' ').slice(0, 70)}` : ''}`).join('\n');
+  const activity = recent.length
+    ? recent.slice(0, 30).map(r => `  - ${r.text.replace(/\s+/g, ' ').slice(0, 100)}`).join('\n')
+    : '  (no recent activity found)';
+  return `[Skills Atlas — prune] Installed skills (older than ${FRESH_DAYS}d, newest activity below):\n${skills}\n\n` +
+    `The user's recent activity (newest first):\n${activity}\n\n${instruction(dismissed)}`;
+}
+
+module.exports = async function pruneCmd(argv) {
+  const { values, positionals } = parse(argv, ['json']);
+  if (values.help) { console.log(HELP); return; }
+  const sub = positionals[0];
+
+  if (sub === 'clear') {
+    prunestate.clear();
+    console.log(values.json ? JSON.stringify({ cleared: true }) : `${green('✓')} dismissals reset.`);
+    return;
+  }
+  if (sub === 'dismiss') {
+    const x = positionals.slice(1).join(' ');
+    if (!x) { console.error('usage: skills-atlas prune dismiss <skill>'); process.exitCode = 1; return; }
+    prunestate.dismiss(x);
+    console.log(values.json ? JSON.stringify({ dismissed: x }) : `${green('✓')} won't suggest removing: ${x}`);
+    return;
+  }
+
+  const { data } = loadData({ quiet: values.json });
+  const dismissed = prunestate.read().dismissed || [];
+  const installed = reviewList(data, dismissed, Date.now());
+  const recent = transcripts.recentPrompts({ max: 60 });
+
+  if (values.json) { console.log(JSON.stringify({ installed, recent, dismissed }, null, 2)); return; }
+
+  if (!installed.length) {
+    console.log(dim(`nothing to review — no skills installed longer than ${FRESH_DAYS} days.`));
+    console.log(dim('see what you have: skills-atlas installed'));
+    return;
+  }
+  console.log('\n' + digestText(installed, recent, dismissed));
+};
+
+module.exports.reviewList = reviewList;
+module.exports.digestText = digestText;
+module.exports.FRESH_DAYS = FRESH_DAYS;

package/src/commands/suggest.js

@@ -18,6 +18,8 @@ const fsu = require('../fsutil');
 const registry = require('../registry');
 const transcripts = require('../transcripts');
 const gapstate = require('../gapstate');
+const prunestate = require('../prunestate');
+const prune = require('./prune');
 
 const COOLDOWN = 3; // min prompts between suggestions
 const GAP_EVERY = 12; // a gap nudge is only considered at every Nth prompt (per session)
@@ -81,6 +83,26 @@ module.exports = async function suggest() {
       }
     }
 
+    // --- Proactive prune nudge: installed skills that may no longer fit the user's
+    // work. Offset from the gap check so the two never fire on the same prompt. ---
+    if (ap.prune && state.count % GAP_EVERY === Math.floor(GAP_EVERY / 2)) {
+      const recent = transcripts.recentPrompts({ max: 30 });
+      if (recent.length >= 8) {
+        const ps = prunestate.read();
+        const { fire, sig } = gapstate.shouldNudge(ps, recent, Date.now());
+        if (fire) {
+          const { data } = loadData({ quiet: true });
+          const installed = prune.reviewList(data, ps.dismissed || [], Date.now());
+          if (installed.length) {
+            emit(prune.digestText(installed, recent, ps.dismissed || []));
+            prunestate.touchNudge(sig);
+            writeState(file, state);
+            return;
+          }
+        }
+      }
+    }
+
     // --- Per-prompt autopilot (gated by the suggest toggle + cooldown) ---
     if (!ap.suggest) { writeState(file, state); return; }
     if (state.count - (state.lastSuggestedCount ?? -COOLDOWN) < COOLDOWN) { writeState(file, state); return; }

package/src/prunestate.js

@@ -0,0 +1,26 @@
+// Persistence for prune suggestions: which removals the user dismissed, when we
+// last nudged, and the activity fingerprint at that nudge (so a nudge can refire
+// when work shifts to a new task). The refire policy is shared with gaps.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function file() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'skills-atlas', 'prune.json');
+}
+function read() {
+  try { const s = JSON.parse(fs.readFileSync(file(), 'utf8')); if (!Array.isArray(s.dismissed)) s.dismissed = []; return s; }
+  catch { return { dismissed: [], lastNudge: 0 }; }
+}
+function write(s) {
+  try { fs.mkdirSync(path.dirname(file()), { recursive: true }); fs.writeFileSync(file(), JSON.stringify(s)); } catch { /* ignore */ }
+}
+function dismiss(x) { const s = read(); if (x && !s.dismissed.includes(x)) s.dismissed.push(x); write(s); return s; }
+function isDismissed(x) { return read().dismissed.includes(x); }
+function touchNudge(sig) { const s = read(); s.lastNudge = Date.now(); if (sig) s.lastSig = sig; write(s); }
+function clear() { write({ dismissed: [], lastNudge: 0, lastSig: [] }); }
+
+module.exports = { file, read, write, dismiss, isDismissed, touchNudge, clear };

package/src/registry.js

@@ -76,7 +76,7 @@ function removeCachedSource(url) {
 // config.json; read-modify-write the full object so registry `sources` is preserved.
 function getAutopilot() {
   const c = readConfig();
-  return { suggest: true, gapAlerts: true, ...(c.autopilot || {}) };
+  return { suggest: true, gapAlerts: true, prune: false, ...(c.autopilot || {}) };
 }
 function setAutopilot(patch) {
   const c = readConfig();

package/src/search-core.js

@@ -215,6 +215,43 @@ 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
 
+// --- Content anchors (match by FUNCTION, not just name) ----------------------
+// ~a third of catalog skills have opaque names (sentry/grill-me/get-shit-done) that
+// don't contain their function, and Chinese prompts never match an English name at
+// all. So besides the skill NAME, anchor on the curated function text — use_case /
+// group / when, in BOTH languages — with the same distinctiveness gate as names.
+// A content match must include at least one DISTINCTIVE function word to fire, so
+// generic prose overlap stays silent.
+const CONTENT_FIRE_IDF = 4.6;     // weight bar when only one distinctive word matched (+ a 2nd word)
+const CONTENT_DISTINCT_IDF = 3.5; // a word this distinctive (~≤10 rows) counts toward "strong"
+
+// Generic Chinese words that must not fire on their own — the CJK analog of
+// ANCHOR_STOP (casual verbs + generic nouns that carry no domain intent).
+const CJK_ANCHOR_STOP = new Set([
+  '看看', '看下', '看一', '帮忙', '处理', '解决', '完成', '搞定', '试试', '弄一', '做个', '做一',
+  '写个', '写一', '加个', '改改', '改一', '删掉', '运行', '创建', '生成', '修改', '优化', '检查',
+  '一下', '一个', '这个', '那个', '东西', '问题', '代码', '文件', '内容', '功能', '项目', '任务',
+  '系统', '方法', '工具', '数据', '需要', '想要', '怎么', '如何', '可以', '应该', '一些', '这些',
+]);
+
+// Tokens of a row's curated short function text (NOT the long description — keep it
+// distinctive), both languages, for the corpus DF and for matching a query.
+const rowContent = r =>
+  tokenize(lc([r.use_case, r.use_case_en, r.group, r.group_en, r.when_to_use, r.when_to_use_en].filter(Boolean).join(' ')));
+const contentHas = (set, t) => set.has(t) || (t.length > 3 && t.endsWith('s') && set.has(t.slice(0, -1)));
+
+const _contentDfCache = new WeakMap();
+function contentDf(rows) {
+  let info = _contentDfCache.get(rows);
+  if (info) return info;
+  const df = new Map();
+  let n = 0;
+  for (const r of rows) { n++; for (const t of new Set(rowContent(r))) df.set(t, (df.get(t) || 0) + 1); }
+  info = { df, n: n || 1 };
+  _contentDfCache.set(rows, info);
+  return info;
+}
+
 // 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:
@@ -252,10 +289,49 @@ function suggestCandidates(rows, prompt, { installed = new Set(), suggested = ne
   }
   anchors.sort((a, b) => b.weight - a.weight || maxStars(b.row) - maxStars(a.row));
 
+  // 1b. content anchors — match the curated FUNCTION text (use_case / group / when),
+  // so opaque-named skills are findable by what they do and Chinese prompts match at
+  // all. Generic words (ANCHOR_STOP / CJK_ANCHOR_STOP) are excluded up front.
+  const contentTokens = tokens.filter(t => !ANCHOR_STOP.has(t) && !CJK_ANCHOR_STOP.has(t));
+  const contentAnchors = [];
+  if (contentTokens.length) {
+    const cdf = contentDf(rows);
+    for (const r of rows) {
+      const content = new Set(rowContent(r));
+      let weight = 0, strong = 0, matched = 0;
+      for (const t of new Set(contentTokens)) {
+        if (!contentHas(content, t)) continue;
+        matched++;
+        const idf = idfOf(cdf, t);
+        weight += idf;
+        if (idf >= CONTENT_DISTINCT_IDF) strong++; // only distinctive words count as "strong"
+      }
+      if (strong) contentAnchors.push({ row: r, weight, strong, matched });
+    }
+    // Prefer rows matching MORE distinctive function words over an incidental hit.
+    contentAnchors.sort((a, b) => b.strong - a.strong || b.weight - a.weight || maxStars(b.row) - maxStars(a.row));
+  }
+  // Fire/qualify only with a distinctive function match: two distinctive words, or
+  // one distinctive word backed by a second matched word and enough total weight.
+  // (A single distinctive word alone never fires — too easy to hit by coincidence.)
+  const contentQualifies = a => a.strong >= 2 || (a.strong >= 1 && a.matched >= 2 && a.weight >= CONTENT_FIRE_IDF);
+
+  // Merge name + qualifying content anchors into ONE shortlist ranked by strength,
+  // so a strong function match (grill-me: interrogate + stress-test) outranks a
+  // single-word name match (launch) when it's the better fit. runSearch backfills.
+  const ranked0 = [];
+  for (const a of anchors) ranked0.push({ skill: a.skill, row: a.row, strong: a.strong, weight: a.weight });
+  for (const a of contentAnchors) {
+    if (!contentQualifies(a)) continue;
+    const s = (a.row.skills || []).find(x => !taken.has(x));
+    if (s) ranked0.push({ skill: s, row: a.row, strong: a.strong, weight: a.weight });
+  }
+  ranked0.sort((a, b) => b.strong - a.strong || 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); }
+  for (const a of ranked0) { if (out.length >= limit) break; push(a.skill, a.row); }
 
   // 2. fill remaining slots from the general ranked search — but only with rows
   // that are actually on-topic (a name/group hit, or strong coverage). A lone
@@ -276,7 +352,10 @@ function suggestCandidates(rows, prompt, { installed = new Set(), suggested = ne
   // 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);
+  const fire = out.length > 0 && (
+    anchors.some(a => a.strong >= 2 || a.weight >= FIRE_IDF) ||
+    contentAnchors.some(contentQualifies)
+  );
   return { fire, candidates: out.slice(0, limit), weak };
 }