skills-atlas-cli 0.6.1 → 0.7.0

package/README.md

@@ -179,6 +179,15 @@ unless one truly fits, or searches further itself). It's:
 - **safe** — never auto-installs (always your call), and fails open (a hook
   error never blocks your prompt).
 
+**🔭 Capability gaps.** `skills-atlas gaps` shows Claude your *recent activity* and
+lets **Claude** spot the recurring kinds of work you keep doing that no installed
+skill covers yet — then recommend one, with the pattern as evidence. We don't guess
+with heuristics; we just give Claude the memory it lacks (your recent prompts, read
+from Claude Code's own local transcripts — **nothing is stored or sent**) plus the
+catalog. With the hook on, it also nudges in-conversation now and then. The two
+layers are independent: `skills-atlas hook suggest on|off` (per-prompt) and
+`skills-atlas hook gaps on|off` (the proactive nudge).
+
 ## License
 
 MIT. Each installed skill keeps its own source repository's license.

package/bin/skills.js

@@ -14,13 +14,14 @@ const sync = require('../src/commands/sync');
 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 update = require('../src/commands/update');
 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, update, categories, list, registry };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, update, categories, list, registry };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -43,6 +44,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)
 
 catalog:
   update             refresh the catalog from the public data feed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.6.1",
+  "version": "0.7.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/commands/gaps.js

@@ -0,0 +1,61 @@
+// `skills-atlas gaps` — surface the user's recent activity + a judging instruction
+// so CLAUDE (running this in Claude Code) spots recurring needs no skill covers yet.
+// We provide memory (recent prompts) + the ask; Claude does the judgment. No network.
+'use strict';
+
+const { parse } = require('../args');
+const transcripts = require('../transcripts');
+const gapstate = require('../gapstate');
+const { dim, green } = require('../format');
+
+const HELP = `usage: skills-atlas gaps [dismiss <skill> | clear]
+
+Surface your recent Claude Code activity so Claude can spot recurring kinds of work
+no installed skill covers yet. Run it in Claude Code (or ask Claude "any skills I
+should get?"). Reads your local transcripts; nothing is stored or sent.
+
+  gaps                 review recent activity → Claude recommends
+  gaps dismiss <skill> stop recommending one
+  gaps clear           reset dismissals
+  --json`;
+
+const INSTRUCTION = dismissed =>
+  `Identify any recurring KIND of work the user keeps doing that an installable catalog skill ` +
+  `is built for and they haven't installed. For each real recurring need (ignore one-offs and ` +
+  `anything already covered): state the pattern + rough frequency as evidence, then recommend the ` +
+  `skill — verify it exists with \`skills-atlas search "<intent>"\` or \`skills-atlas info <skill>\`, ` +
+  `and install with \`skills-atlas use <skill> --yes\`.` +
+  (dismissed.length ? ` Already dismissed (skip these): ${dismissed.join(', ')}.` : '') +
+  ` If nothing clearly recurs, say there are no gaps.`;
+
+module.exports = async function gapsCmd(argv) {
+  const { values, positionals } = parse(argv, ['json', 'yes']);
+  if (values.help) { console.log(HELP); return; }
+  const sub = positionals[0];
+
+  if (sub === 'clear') {
+    gapstate.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 gaps dismiss <skill>'); process.exitCode = 1; return; }
+    gapstate.dismiss(x);
+    console.log(values.json ? JSON.stringify({ dismissed: x }) : `${green('✓')} dismissed: ${x}`);
+    return;
+  }
+
+  const recent = transcripts.recentPrompts({ max: 60 });
+  const dismissed = (gapstate.read().dismissed) || [];
+  if (values.json) { console.log(JSON.stringify({ recent, dismissed }, null, 2)); return; }
+
+  if (!recent.length) {
+    console.log(dim('no recent activity found to analyze.'));
+    console.log(dim('gaps are spotted from your recent Claude Code prompts — use it for a while, then run this in a session.'));
+    return;
+  }
+  const days = Math.max(1, Math.round((Date.now() - recent[recent.length - 1].ts) / 86400000));
+  const lines = recent.slice(0, 40).map(r => `  - ${r.text.replace(/\s+/g, ' ').slice(0, 100)}`).join('\n');
+  console.log(`\n[Skills Atlas — capability gaps] The user's recent requests across sessions (${recent.length} over ~${days} day(s), newest first):\n${lines}\n\n${INSTRUCTION(dismissed)}`);
+};

package/src/commands/hook.js

@@ -9,6 +9,7 @@ const os = require('os');
 const path = require('path');
 const { parse } = require('../args');
 const { green, dim } = require('../format');
+const registry = require('../registry');
 
 const HOOK_CMD = 'skills-atlas suggest';
 const settingsPath = () => path.join(os.homedir(), '.claude', 'settings.json');
@@ -22,21 +23,37 @@ 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>'); return; }
+  if (values.help) { console.log('usage: skills-atlas hook <on|off|status|suggest on|off|gaps on|off>'); return; }
   const sub = positionals[0] || 'status';
   const p = settingsPath();
 
+  if (sub === 'suggest' || sub === 'gaps') {
+    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';
+    registry.setAutopilot({ [key]: onoff === 'on' });
+    const label = sub === 'suggest' ? 'per-prompt autopilot' : 'gap alerts';
+    console.log(`${green('✓')} ${label}: ${onoff === 'on' ? green('on') : dim('off')}`);
+    return;
+  }
+
   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)}`);
+    const ap = registry.getAutopilot();
+    if (values.json) { console.log(JSON.stringify({ enabled: on, suggest: ap.suggest, gapAlerts: ap.gapAlerts, settings: p })); return; }
+    console.log(`autopilot hook: ${on ? green('on') : dim('off')}   ${dim(p)}`);
+    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)')}`);
+    if (on) console.log(dim('  review gaps: skills-atlas gaps'));
     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>');
+    console.error('usage: skills-atlas hook <on|off|status|suggest on|off|gaps on|off>');
     process.exitCode = 1;
     return;
   }

package/src/commands/suggest.js

@@ -15,8 +15,13 @@ const { buildIndices } = require('../index-build');
 const { suggestCandidates } = require('../search-core');
 const manifest = require('../manifest');
 const fsu = require('../fsutil');
+const registry = require('../registry');
+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)
 
 function stateFile(sessionId) {
   const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
@@ -31,6 +36,10 @@ function writeState(f, s) {
   try { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, JSON.stringify(s)); } catch { /* ignore */ }
 }
 
+function emit(ctx) {
+  console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } }));
+}
+
 module.exports = async function suggest() {
   try {
     if (process.stdin.isTTY) {
@@ -47,25 +56,48 @@ module.exports = async function suggest() {
     const file = stateFile(event.session_id || event.sessionId);
     const state = readState(file);
     state.count = (state.count || 0) + 1;
+    const ap = registry.getAutopilot();
+
+    // --- Proactive gap nudge: periodic + throttled to once/day; Claude judges ---
+    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 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));
+          emit(`[Skills Atlas — capability gaps] The user's recent requests (${recent.length} over ~${days} day(s), newest first):\n${lines}\n` +
+            `If a recurring KIND of work stands out that an installable catalog skill is built for and they haven't ` +
+            `installed (ignore one-offs), name the pattern with rough frequency as evidence and recommend it — verify with ` +
+            `\`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();
+          writeState(file, state);
+          return;
+        }
+      }
+    }
 
-    // cooldown — don't suggest on every prompt
+    // --- 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; }
 
     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 { fire, candidates } = suggestCandidates(flatRows, prompt, { installed, suggested });
-    if (!fire) { writeState(file, state); return; }
+    if (!fire || !candidates.length) { writeState(file, state); return; }
 
     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 =
+    emit(
       `[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` +
@@ -75,9 +107,7 @@ module.exports = async function suggest() {
       `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 } }));
-
+      `at all — don't mention this hook, these skills, or that a suggestion was made.`);
     state.lastSuggestedCount = state.count;
     state.suggested = [...suggested, ...candidates.map(c => c.skill)];
     writeState(file, state);

package/src/gapstate.js

@@ -0,0 +1,25 @@
+// 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.)
+'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', 'gaps.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() { const s = read(); s.lastNudge = Date.now(); write(s); }
+function clear() { write({ dismissed: [], lastNudge: 0 }); }
+
+module.exports = { file, read, write, dismiss, isDismissed, touchNudge, clear };

package/src/registry.js

@@ -72,7 +72,21 @@ function removeCachedSource(url) {
   try { fs.rmSync(sourceCachePath(url), { force: true }); } catch { /* ignore */ }
 }
 
+// Autopilot toggles (per-prompt suggest + proactive gap alerts) share this
+// 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 || {}) };
+}
+function setAutopilot(patch) {
+  const c = readConfig();
+  c.autopilot = { ...getAutopilot(), ...patch };
+  writeConfig(c);
+  return c.autopilot;
+}
+
 module.exports = {
   configDir, configFile, readConfig, writeConfig, addSource, removeSource, listSources,
   effectiveSources, sourceCachePath, cacheSource, readCachedSource, removeCachedSource,
+  getAutopilot, setAutopilot,
 };

package/src/transcripts.js

@@ -0,0 +1,73 @@
+// Read the user's recent TYPED prompts from Claude Code's local session transcripts
+// (JSONL under ~/.claude/projects/<proj>/<session>.jsonl). We store nothing new —
+// this is the user's own data, read locally, only ever shown to the local Claude.
+// Validated against real transcripts: a typed prompt has type:"user",
+// message.role:"user", and a STRING content (tool results have array content).
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DAY = 86400000;
+const MAX_BYTES = 1_500_000; // cap per-file read (hook runs under a 5s timeout); recent prompts are at the file's tail
+const projectsDir = () => path.join(os.homedir(), '.claude', 'projects');
+
+function fromFile(file, sinceMs) {
+  const out = [];
+  let text;
+  try {
+    const st = fs.statSync(file);
+    if (st.size <= MAX_BYTES) {
+      text = fs.readFileSync(file, 'utf8');
+    } else {
+      // tail-read only the last MAX_BYTES, then drop the partial first line
+      const fd = fs.openSync(file, 'r');
+      try {
+        const b = Buffer.alloc(MAX_BYTES);
+        fs.readSync(fd, b, 0, MAX_BYTES, st.size - MAX_BYTES);
+        text = b.toString('utf8');
+      } finally { fs.closeSync(fd); }
+      const nl = text.indexOf('\n');
+      text = nl >= 0 ? text.slice(nl + 1) : text;
+    }
+  } catch { return out; }
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    let o; try { o = JSON.parse(line); } catch { continue; }
+    if (o.type !== 'user' || o.isSidechain) continue;
+    const m = o.message;
+    if (!m || m.role !== 'user' || typeof m.content !== 'string') continue;
+    const t = m.content.trim();
+    if (!t || t.startsWith('<') || t.includes('<command-name>') || t.includes('<local-command')) continue;
+    const ts = Date.parse(o.timestamp);
+    if (!Number.isFinite(ts) || (sinceMs && ts < sinceMs)) continue; // drop missing/unparseable/out-of-window
+    out.push({ text: t, ts, cwd: o.cwd || null });
+  }
+  return out;
+}
+
+function recentPrompts({ windowDays = 21, max = 60, now = Date.now() } = {}) {
+  const sinceMs = now - windowDays * DAY;
+  const dir = projectsDir();
+  const files = [];
+  try {
+    for (const proj of fs.readdirSync(dir)) {
+      const pdir = path.join(dir, proj);
+      let entries; try { entries = fs.readdirSync(pdir); } catch { continue; }
+      for (const f of entries) {
+        if (!f.endsWith('.jsonl')) continue;
+        const fp = path.join(pdir, f);
+        let mt = 0; try { mt = fs.statSync(fp).mtimeMs; } catch { /* ignore */ }
+        if (mt >= sinceMs) files.push({ fp, mt });
+      }
+    }
+  } catch { return []; }
+  files.sort((a, b) => b.mt - a.mt);
+  let all = [];
+  for (const { fp } of files.slice(0, 40)) all = all.concat(fromFile(fp, sinceMs));
+  all.sort((a, b) => b.ts - a.ts);
+  return all.slice(0, max);
+}
+
+module.exports = { recentPrompts, fromFile, projectsDir };