skills-atlas-cli 0.8.4 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.8.4",
+  "version": "0.8.7",
   "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/suggest.js

@@ -20,8 +20,7 @@ const transcripts = require('../transcripts');
 const gapstate = require('../gapstate');
 
 const COOLDOWN = 3; // min prompts between suggestions
-const GAP_EVERY = 12;                 // earliest a gap nudge may fire (per session)
-const NUDGE_COOLDOWN_MS = 24 * 3600000; // and at most one gap nudge per day (across sessions)
+const GAP_EVERY = 12; // a gap nudge is only considered at every Nth prompt (per session)
 
 function stateFile(sessionId) {
   const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
@@ -58,12 +57,14 @@ module.exports = async function suggest() {
     state.count = (state.count || 0) + 1;
     const ap = registry.getAutopilot();
 
-    // --- Proactive gap nudge: periodic + throttled to once/day; Claude judges ---
+    // --- Proactive gap nudge: periodic, and refired when the recurring work shifts
+    // to something new (anti-spam floor + activity fingerprint, not a daily clock) ---
     if (ap.gapAlerts && state.count % GAP_EVERY === 0) {
-      const gs = gapstate.read();
-      if (Date.now() - (gs.lastNudge || 0) >= NUDGE_COOLDOWN_MS) {
-        const recent = transcripts.recentPrompts({ max: 20 });
-        if (recent.length >= 8) {
+      const recent = transcripts.recentPrompts({ max: 20 });
+      if (recent.length >= 8) {
+        const gs = gapstate.read();
+        const { fire, sig } = gapstate.shouldNudge(gs, recent, Date.now());
+        if (fire) {
           const dismissed = gs.dismissed || [];
           const lines = recent.map(r => `- ${r.text.replace(/\s+/g, ' ').slice(0, 100)}`).join('\n');
           const days = Math.max(1, Math.round((Date.now() - recent[recent.length - 1].ts) / 86400000));
@@ -73,7 +74,7 @@ module.exports = async function suggest() {
             `\`skills-atlas info <skill>\` and install with \`skills-atlas use <skill> --yes\`.` +
             (dismissed.length ? ` Already dismissed (skip): ${dismissed.join(', ')}.` : '') +
             ` If nothing clearly recurs or it doesn't fit right now, stay silent.`);
-          gapstate.touchNudge();
+          gapstate.touchNudge(sig);
           writeState(file, state);
           return;
         }

package/src/gapstate.js

@@ -1,10 +1,18 @@
 // The only thing capability-gaps persists: which suggestions the user dismissed,
-// and when we last proactively nudged. (Judgment is Claude's; no prompt text here.)
+// when we last proactively nudged, and a fingerprint of what the user was doing at
+// that nudge. (Judgment is Claude's; no prompt text is stored — only token stems.)
 'use strict';
 
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { tokenize } = require('./search-core');
+
+// Gap nudges are gated by activity, not a wall clock: a short anti-spam floor, then
+// a refire whenever the recurring work shifts to something new (so it can catch the
+// user on their NEXT task), plus a long fallback so a persistent gap can resurface.
+const MIN_INTERVAL_MS = 90 * 60 * 1000;          // ~90 min: never two nudges in a burst
+const REFRESH_INTERVAL_MS = 12 * 60 * 60 * 1000; // ~12 h: an unchanged gap may resurface
 
 function file() {
   const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
@@ -19,7 +27,45 @@ function write(s) {
 }
 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() { const s = read(); s.lastNudge = Date.now(); write(s); }
-function clear() { write({ dismissed: [], lastNudge: 0 }); }
+function touchNudge(sig) { const s = read(); s.lastNudge = Date.now(); if (sig) s.lastSig = sig; write(s); }
+function clear() { write({ dismissed: [], lastNudge: 0, lastSig: [] }); }
+
+// A coarse fingerprint of recent work: the most frequent contentful tokens across
+// recent prompts. When this set shifts, the user has moved to a new kind of work.
+function activitySignature(prompts, topN = 8) {
+  const freq = new Map();
+  for (const p of prompts || []) {
+    const text = typeof p === 'string' ? p : (p && p.text) || '';
+    for (const t of tokenize(String(text).toLowerCase())) freq.set(t, (freq.get(t) || 0) + 1);
+  }
+  return [...freq.entries()]
+    .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+    .slice(0, topN).map(e => e[0]).sort();
+}
+
+// Did the dominant activity shift by more than half (Jaccard < 0.5)? No prior → yes.
+function signatureShifted(sig, prev) {
+  if (!prev || !prev.length) return true;
+  const a = new Set(sig);
+  if (!a.size) return false;
+  const b = new Set(prev);
+  let inter = 0; for (const x of a) if (b.has(x)) inter++;
+  const union = new Set([...a, ...b]).size || 1;
+  return inter / union < 0.5;
+}
+
+// Smart-refire decision (pure). Fire when past the anti-spam floor AND either the
+// activity shifted to something new, or the long fallback has elapsed.
+function shouldNudge(state, recent, now) {
+  const sig = activitySignature(recent);
+  const since = now - ((state && state.lastNudge) || 0);
+  if (since < MIN_INTERVAL_MS) return { fire: false, sig };
+  const fire = signatureShifted(sig, state && state.lastSig) || since >= REFRESH_INTERVAL_MS;
+  return { fire, sig };
+}
 
-module.exports = { file, read, write, dismiss, isDismissed, touchNudge, clear };
+module.exports = {
+  file, read, write, dismiss, isDismissed, touchNudge, clear,
+  activitySignature, signatureShifted, shouldNudge,
+  MIN_INTERVAL_MS, REFRESH_INTERVAL_MS,
+};

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 };
 }