skills-atlas-cli 0.8.2 → 0.8.5

package/package.json

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

@@ -1,9 +1,27 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const { parse } = require('../args');
 const { loadData } = require('../data');
 const { buildIndices, suggestSkills } = require('../index-build');
 const { buildInfo, renderInfo, dim } = require('../format');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+
+// The authoritative one-liner: a skill's own SKILL.md `description:` frontmatter,
+// read locally when installed (offline). Catalog text is group-level; this is not.
+function localSkillDesc(skill) {
+  for (const s of fsu.scopesFor({})) {
+    try {
+      const md = fs.readFileSync(path.join(s.root, skill, 'SKILL.md'), 'utf8');
+      const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      const dm = fm && fm[1].match(/^description:\s*(.+)$/m);
+      if (dm) return dm[1].trim().replace(/^["']|["']$/g, '');
+    } catch { /* not installed in this scope */ }
+  }
+  return '';
+}
 
 const HELP = `usage: skills-atlas info <skill> [--all] [--json] [--zh]
 
@@ -44,5 +62,8 @@ module.exports = async function info(argv) {
     console.log(JSON.stringify(infoObj, null, 2));
     return;
   }
-  console.log(renderInfo(infoObj, { en: !values.zh, all: values.all }));
+  const installed = [];
+  for (const s of fsu.scopesFor({})) if (manifest.list(s.root).some(e => e.skill === infoObj.skill)) installed.push(s.name);
+  const skillDesc = installed.length ? localSkillDesc(infoObj.skill) : '';
+  console.log(renderInfo(infoObj, { en: !values.zh, all: values.all, installed, skillDesc }));
 };

package/src/commands/search.js

@@ -5,6 +5,8 @@ const { loadData } = require('../data');
 const { buildIndices, suggestSkills } = require('../index-build');
 const { runSearch } = require('../search-core');
 const { renderRow, dim } = require('../format');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
 
 const HELP = `usage: skills-atlas search <query...> [filters]
 
@@ -86,7 +88,9 @@ module.exports = async function search(argv) {
   if (weak) {
     console.log(dim('\n⚠ partial match — results may cover only part of your query; the top ones can still help, or try different words.'));
   }
-  shown.forEach(r => console.log(renderRow(r, { en })));
+  const installedSet = new Set();
+  for (const s of fsu.scopesFor({})) for (const e of manifest.list(s.root)) installedSet.add(e.skill);
+  shown.forEach(r => console.log(renderRow(r, { en, installed: installedSet, vendors: data.vendors })));
   const truncated = rows.length > limit;
   console.log(`\n${rows.length} match(es)${truncated ? `, showing ${limit}` : ''}.`);
   if (truncated) console.log(dim(`see the rest with --limit ${rows.length}${values.category ? '' : ', or narrow with -c <category>'}.`));

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

@@ -19,6 +19,17 @@ function stars(n) {
   return `★${n}`;
 }
 
+// Repo freshness from a source's `last_commit` ("2026-05-28"). Returns null if
+// absent/unparseable. `stale` flags a repo untouched for over a year — so a popular
+// but abandoned source no longer looks identical to an actively maintained one.
+function recency(lastCommit, now = Date.now()) {
+  if (!lastCommit) return null;
+  const t = Date.parse(lastCommit);
+  if (!Number.isFinite(t)) return null;
+  const days = Math.floor((now - t) / 86400000);
+  return { date: String(lastCommit).slice(0, 10), days, stale: days > 365 };
+}
+
 // A `git clone <repo> ~/.claude/skills/skills` alt double-nests a multi-skill
 // monorepo (skills end up at .claude/skills/skills/<name>/) and won't load —
 // drop that foot-gun; the `npx skills add` command is the correct path.
@@ -34,8 +45,10 @@ function text(obj, key, en) {
   return en ? (obj[key + '_en'] || obj[key] || '') : (obj[key] || obj[key + '_en'] || '');
 }
 
-// One search/list result line block.
-function renderRow(r, { en = false } = {}) {
+// One search/list result line block. `installed` (a Set of skill names) marks what
+// you already have; `vendors` lets the source line say whether install is a clean
+// single-skill folder or a whole-repo command.
+function renderRow(r, { en = false, installed = null, vendors = null } = {}) {
   const chain = r.chain ? cyan('⛓ ') : '';
   const cat = en ? (r._catEn || r._cat) : r._cat;
   const lines = [`\n${chain}${bold(text(r, 'group', en))}   ${dim('[' + cat + ']')}`];
@@ -43,14 +56,22 @@ function renderRow(r, { en = false } = {}) {
   if (uc) lines.push(`  💡 ${uc}`);
   const SK_MAX = 8;
   const sk = r.skills || [];
+  const tick = s => (installed && installed.has(s)) ? green(s + ' ✓') : green(s);
   const skStr = sk.length > SK_MAX
-    ? green(sk.slice(0, SK_MAX).join(', ')) + dim(` +${sk.length - SK_MAX} more`)
-    : green(sk.join(', '));
+    ? sk.slice(0, SK_MAX).map(tick).join(dim(', ')) + dim(` +${sk.length - SK_MAX} more`)
+    : sk.map(tick).join(dim(', '));
   lines.push(`  ${dim('skills:')} ${skStr}`);
   const best = [...(r.sources || [])].sort((a, b) => (b.stars || 0) - (a.stars || 0))[0];
   if (best) {
+    const rec = recency(best.last_commit);
+    const recStr = rec ? `  updated ${rec.date}${rec.stale ? ' ⚠' : ''}` : '';
+    let kind = '';
+    if (vendors) {
+      const v = vendors[best.name];
+      kind = (v && skillDocPath(v, sk[0])) ? '  [single-skill]' : '  [whole-repo]';
+    }
     const inst = best.install && best.install.command ? ` — ${best.install.command}` : '';
-    lines.push(`  ${dim('via')} ${best.name} ${yellow(stars(best.stars))}${dim(inst)}`);
+    lines.push(`  ${dim('via')} ${best.name} ${yellow(stars(best.stars))}${dim(recStr)}${dim(kind)}${dim(inst)}`);
   }
   return lines.join('\n');
 }
@@ -89,6 +110,7 @@ function groupOf(r, skillName, vendors) {
         id: s.name,
         url: s.url,
         stars: s.stars,
+        last_commit: s.last_commit || v.last_commit || null,
         license: (v.skill_licenses && v.skill_licenses[skillName]) || s.license || null,
         type: s.type,
         path: docPath || null,
@@ -128,15 +150,40 @@ function infoForRow(skillName, row, vendors) {
   return { skill: skillName, found: true, groups: [groupOf(row, skillName, vendors)] };
 }
 
-function renderInfo(info, { en = false, all = false } = {}) {
+// Multi-skill groups share one description that often enumerates each skill as
+// "<vendor> <skill> (<detail>) + …". Pull out the segment for THIS skill so info
+// pinpoints what it does, not just the whole group. Conservative: only fire when
+// the skill matches exactly one segment (otherwise we'd guess wrong).
+function perSkillBlurb(skill, desc) {
+  if (!skill || !desc) return '';
+  const segs = String(desc).split(' + ');
+  if (segs.length < 2) return '';
+  const re = new RegExp('\\b' + String(skill).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'i');
+  const hits = segs.filter(s => re.test(s));
+  if (hits.length !== 1) return '';
+  const seg = hits[0].trim();
+  return /[(（]/.test(seg) ? seg : '';   // only worth showing if it carries a detail
+}
+
+// `skillDesc` is the authoritative one-liner from the skill's own SKILL.md (read
+// locally when installed); it wins over the heuristic catalog-segment extraction.
+function renderInfo(info, { en = false, all = false, installed = null, skillDesc = '' } = {}) {
   const pick = (zh, e) => (en ? (e || zh) : (zh || e)) || '';
   const out = [];
-  out.push(`\n${bold(green(info.skill))}${info.groups.some(g => g.chain) ? ' ' + cyan('⛓') : ''}`);
+  const instTag = installed && installed.length
+    ? ` ${green('✓ installed')} ${dim('[' + installed.join('+') + ']')}` : '';
+  out.push(`\n${bold(green(info.skill))}${info.groups.some(g => g.chain) ? ' ' + cyan('⛓') : ''}${instTag}`);
   const shown = all ? info.groups : info.groups.slice(0, 1);
+  let firstGroup = true;
   for (const g of shown) {
     out.push(`  ${dim('group:')} ${pick(g.group, g.group_en)}  ${dim('[' + pick(g.category, g.category_en) + ']')}`);
     const desc = pick(g.description, g.description_en);
-    if (desc) out.push(`  ${desc}`);
+    const blurb = (firstGroup && skillDesc) ? skillDesc : perSkillBlurb(info.skill, desc);
+    firstGroup = false;
+    const distinguished = blurb && blurb !== desc;
+    if (distinguished) out.push(`  ${dim('this skill:')} ${blurb}`);
+    // Only call it "group does:" when a per-skill line is shown above it to contrast.
+    if (desc) out.push(distinguished ? `  ${dim('group does:')} ${desc}` : `  ${desc}`);
     const uc = pick(g.use_case, g.use_case_en);
     if (uc) out.push(`  ${dim('use case:')} ${uc}`);
     const wt = pick(g.when_to_use, g.when_to_use_en);
@@ -146,7 +193,9 @@ function renderInfo(info, { en = false, all = false } = {}) {
     }
     out.push(`  ${dim('sources:')}`);
     for (const s of g.sources) {
-      out.push(`    • ${bold(s.id)} ${yellow(stars(s.stars))} ${dim(s.type || '')} ${s.license ? dim('(' + s.license + ')') : ''}`);
+      const rec = recency(s.last_commit);
+      const recStr = rec ? `  ${dim('updated ' + rec.date)}${rec.stale ? ' ' + yellow('⚠ stale') : ''}` : '';
+      out.push(`    • ${bold(s.id)} ${yellow(stars(s.stars))} ${dim(s.type || '')} ${s.license ? dim('(' + s.license + ')') : ''}${recStr}`);
       out.push(`      ${dim(s.url)}`);
       out.push(`      ${dim('path:')} ${s.path || dim('(whole-repo install — no per-skill folder)')}`);
       if (s.install && s.install.command) {
@@ -166,6 +215,6 @@ function renderInfo(info, { en = false, all = false } = {}) {
 }
 
 module.exports = {
-  bold, dim, green, cyan, yellow, stars, safeAlt, text, renderRow,
+  bold, dim, green, cyan, yellow, stars, recency, perSkillBlurb, safeAlt, text, renderRow,
   buildInfo, infoForRow, renderInfo, PERSONA_EN,
 };

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