skills-atlas-cli 0.9.0 → 0.10.0

package/README.md

@@ -70,9 +70,12 @@ skills-atlas doctor                            # health check: orphans, drift, l
 skills-atlas kit                               # detect this project & install the right skills for it
 skills-atlas sync                              # reproduce a project's kit (skills-atlas.kit.json)
 
-# 🤖 Autopilot & capability gaps   (opt-in)
+# 🤖 Autopilot, gaps & cleanup   (opt-in)
 skills-atlas hook on                           # Claude proactively offers a fitting skill as you work
+skills-atlas hook lang en|zh                   # language the autopilot replies in (default English)
+skills-atlas hook model                        # which model powers gaps/cleanup (default Haiku)
 skills-atlas gaps                              # Claude spots kinds of work you keep doing without a skill
+skills-atlas prune                             # Claude flags installed skills you no longer use
 
 # 🌐 Catalog & sources
 skills-atlas categories                        # the 20 top-level categories
@@ -86,44 +89,37 @@ skills-atlas mcp                               # run as an MCP server (any MCP c
 
 **⛓ Workflows, not just skills.** Many skills belong to a curated chain (e.g.
 `brainstorming → writing-plans → executing-plans → …`). `install <skill> --chain`
-installs the whole pipeline in one archive download, ready to run in order.
+installs the whole pipeline in one step, ready to run in order.
 
 **📦 Project kits.** `skills-atlas kit` detects what this project is (frontend / backend /
 data / infra) and installs a tailored set (a universal dev workflow plus archetype
 add-ons) into `./.claude/skills/`, then writes a committable `skills-atlas.kit.json`.
 A teammate runs `skills-atlas sync` to reproduce it exactly.
 
-Output is English by default; add `--zh` for Chinese, or `--json` to any command for machine-readable output.
-After installing a skill, start a new Claude Code session to load it.
-
-## How install works
-
-The real value is the **catalog**: `search` / `info` / `categories` work fully
-offline and map *which* skill fits. It's function-organized, bilingual, tagged with
-use-case / when-to-use / personas / ⛓ chains. That's what `npx skills add` and
-GitHub search don't give you.
+**Where skills land.** Running `install` / `use` yourself installs **globally**
+(`~/.claude/skills/`, every project) — for general workflows you want everywhere. Skills
+suggested by autopilot, installed via the Claude Code plugin, or set up by `kit` go into
+**this project** (`./.claude/skills/`, committable for teammates). Override either way
+with `--global` / `--project`.
 
-On top of that, `install` can place a skill straight into `.claude/skills/`:
+Output is English by default; add `--zh` for Chinese.
+After installing a skill, start a new Claude Code session to load it.
 
-- For a repo that exposes a **per-skill folder**, it downloads only that folder
-  (via the repo archive, with **no GitHub API rate limit**) into
-  `<target>/.claude/skills/<skill>/`, not the whole repo.
-- Several sources? The best installable one is auto-picked. Pass `--source <id>` to
-  choose, `--yes` for non-interactive runs.
-- Other sources (whole-repo / marketplace) print their official command instead
-  (e.g. `npx skills add owner/repo`).
-- `GITHUB_TOKEN` is only needed if you fall back to the API and hit its 60/h limit.
+## Why a catalog
 
-## Keeping the catalog fresh
+`search` / `info` / `categories` work fully offline and tell you *which* skill fits —
+organized by function, bilingual, tagged with use-case, when-to-use, personas and ⛓
+chains. `install` then drops just that skill's folder into `.claude/skills/` (not the
+whole repo); when several repos offer the same skill, the best one is picked for you.
 
-The catalog ships inside the package and works offline. `skills-atlas update` pulls
-the latest from the public feed (cached under `~/.cache/skills-atlas/`).
+The catalog ships with the tool and works offline, and refreshes itself in the
+background so new skills show up on their own. Run `skills-atlas update` to pull the
+latest on demand.
 
-## Private / org catalog sources
+## Your org's private skills
 
-Point the CLI at your organization's own catalog (a `data.json` in the same
-schema) so internal skills show up in `search` / `info` / `install` / `kit`
-alongside the public Atlas:
+Point the CLI at your organization's own catalog so internal skills show up in
+`search` / `info` / `install` / `kit` alongside the public Atlas:
 
 ```bash
 skills-atlas registry add https://skills.acme.internal/data.json   # or a local path
@@ -131,10 +127,7 @@ skills-atlas registry list
 skills-atlas registry remove https://skills.acme.internal/data.json
 ```
 
-Private skills **merge** with the public catalog (a private source wins a same-name
-clash). Sources are cached locally and merged offline. For a private URL behind
-auth, set `SKILLS_ATLAS_TOKEN` (sent as a Bearer header); in CI,
-`SKILLS_ATLAS_SOURCES=url1,url2` adds sources without touching config.
+Private skills merge with the public catalog (your own wins a name clash) and are cached locally.
 
 ## In Claude Code
 
@@ -149,9 +142,9 @@ Just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
 
 ## In any MCP client
 
-`skills-atlas mcp` runs a zero-dependency [MCP](https://modelcontextprotocol.io)
-server over stdio, so any MCP-capable client (Claude Desktop, other agents) can use
-the catalog. Add it to your client's config:
+`skills-atlas mcp` runs an [MCP](https://modelcontextprotocol.io) server so any
+MCP-capable client (Claude Desktop, other agents) can use the catalog. Add it to your
+client's config:
 
 ```json
 { "mcpServers": { "skills-atlas": { "command": "npx", "args": ["-y", "skills-atlas-cli", "mcp"] } } }
@@ -164,37 +157,35 @@ anywhere.
 ## Autopilot (opt-in): the right skill finds you
 
 ```bash
-skills-atlas hook on      # enable    (skills-atlas hook off / status)
+skills-atlas hook on      # turn it on   (hook off / hook status)
+```
+
+With autopilot on, whenever what you're doing lines up with a catalog skill you don't
+have, Claude offers it — explained, with one tap to use it now, see what it covers, or
+skip. You don't have to know the skill exists. It's **off by default**, **quiet** (stays
+silent on greetings and generic asks, never repeats itself, never suggests a skill you
+already have), and **safe** (never auto-installs; a hiccup never blocks your prompt).
+
+Two more proactive helpers:
+
+- **🔭 Capability gaps** — `skills-atlas gaps` notices the recurring kinds of work you
+  keep doing without a skill, and recommends one.
+- **🧹 Cleanup** — `skills-atlas prune` flags installed skills you no longer use and
+  offers to remove them (never on its own; recent installs are left alone).
+
+Tune it to taste:
+
+```bash
+skills-atlas hook suggest on|off    # the per-prompt suggestions
+skills-atlas hook gaps on|off       # gap recommendations            (on by default)
+skills-atlas hook prune on|off      # cleanup suggestions            (off by default)
+skills-atlas hook model [name]      # which model powers gaps/cleanup   (default Haiku)
+skills-atlas hook lang en|zh        # the language it replies in        (default English)
 ```
 
-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. If it
-does, Claude 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 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. Claude is the
-  final filter on relevance.
-- **Local and 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
-  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).
+The per-prompt suggestions are matched on your own machine and sent nowhere. The gaps
+and cleanup helpers hand your recent activity to the model you picked (the same provider
+Claude Code already uses) to judge it.
 
 ## License
 

package/bin/skills.js

@@ -17,6 +17,7 @@ const hook = require('../src/commands/hook');
 const gaps = require('../src/commands/gaps');
 const gapAnalyze = require('../src/commands/gap-analyze');
 const prune = require('../src/commands/prune');
+const feedback = require('../src/commands/feedback');
 const update = require('../src/commands/update');
 const mcp = require('../src/commands/mcp');
 const { categories, list } = require('../src/commands/categories');
@@ -24,7 +25,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, 'gap-analyze': gapAnalyze, prune, update, categories, list, registry, mcp };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, gaps, 'gap-analyze': gapAnalyze, prune, feedback, update, categories, list, registry, mcp };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -49,6 +50,7 @@ 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
+  feedback           what the autopilot learned from your installs/removes (sharpens it)
 
 catalog:
   update             refresh the catalog from the public data feed

package/package.json

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

@@ -0,0 +1,53 @@
+// `skills-atlas feedback` — the autopilot's local suppression list. Two scopes:
+// skills you've dismissed (never suggested, anywhere) and skills you've removed from
+// THIS project (not suggested here). Show / add to / reset it. Nothing is sent.
+'use strict';
+
+const { parse } = require('../args');
+const feedback = require('../feedback');
+const { green, dim } = require('../format');
+
+const HELP = `usage: skills-atlas feedback [dismiss <skill> | reset]
+
+Skills the autopilot won't suggest again. Two kinds, local only — nothing is sent:
+  • dismissed — you said "never suggest this"; applies in every project
+  • removed   — you removed it from THIS project; suppressed here only
+Installing a skill clears both. (Removing one from the global scope is just an
+uninstall — it does not suppress; use 'dismiss' for a blanket no.)
+
+  feedback                  show the suppression list (this project + global)
+  feedback dismiss <skill>  never suggest a skill again, in any project
+  feedback reset            forget everything (global + this project)
+  --json`;
+
+module.exports = async function feedbackCmd(argv) {
+  const { values, positionals } = parse(argv, ['json']);
+  if (values.help) { console.log(HELP); return; }
+  const sub = positionals[0];
+
+  if (sub === 'reset') {
+    feedback.clear();
+    console.log(values.json ? JSON.stringify({ reset: true }) : `${green('✓')} feedback reset.`);
+    return;
+  }
+  if (sub === 'dismiss') {
+    const x = positionals.slice(1).join(' ');
+    if (!x) { console.error('usage: skills-atlas feedback dismiss <skill>'); process.exitCode = 1; return; }
+    feedback.dismiss(x);
+    console.log(values.json ? JSON.stringify({ dismissed: x }) : `${green('✓')} won't suggest ${x} again (any project).`);
+    return;
+  }
+
+  const cur = feedback.current();
+  if (values.json) {
+    console.log(JSON.stringify({ dismissed: [...cur.global], removedHere: [...cur.project] }, null, 2));
+    return;
+  }
+  if (!cur.global.size && !cur.project.size) {
+    console.log(dim('nothing suppressed — run `skills-atlas feedback dismiss <skill>`, or remove a\nskill from this project, and the autopilot stops offering it.'));
+    return;
+  }
+  if (cur.global.size) console.log(`\n${green("won't suggest anywhere")} (${cur.global.size}): ${[...cur.global].join(', ')}`);
+  if (cur.project.size) console.log(`${green("won't suggest in this project")} (${cur.project.size}): ${[...cur.project].join(', ')}`);
+  console.log(dim('re-install one to clear it, or: skills-atlas feedback reset'));
+};

package/src/commands/gaps.js

@@ -29,7 +29,7 @@ const INSTRUCTION = dismissed =>
   `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\`.` +
+  `and install with \`skills-atlas use <skill> --yes --project\`.` +
   (dismissed.length ? ` Already dismissed (skip these): ${dismissed.join(', ')}.` : '') +
   ` If nothing clearly recurs, say there are no gaps.`;
 

package/src/commands/install.js

@@ -253,6 +253,9 @@ module.exports = async function install(argv) {
     return;
   }
 
+  // installing clears any prior suppression (global dismiss + this project's removal).
+  try { require('../feedback').installed(skill); } catch { /* ignore */ }
+
   if (values.json) {
     const out = {
       skill, mode: 'folder', source: src.name,

package/src/commands/remove.js

@@ -40,6 +40,11 @@ module.exports = async function remove(argv) {
   if (fsu.dirExists(dest)) fsu.rmrf(dest);
   manifest.remove(root, name);
 
+  // Removing a PROJECT skill is a "not in this project" signal — suppress it here only,
+  // never across projects (it may be useful elsewhere). Removing a GLOBAL skill is just
+  // uninstalling; for a blanket "never suggest this", use `feedback dismiss`.
+  if (!global) { try { require('../feedback').removedInProject(name); } catch { /* ignore */ } }
+
   if (values.json) { console.log(JSON.stringify({ removed: name, dest })); return; }
   console.log(`${green('✓')} removed ${name}  ${dim(fsu.tildify(dest))}`);
   if (otherHas) console.log(dim(`note: '${name}' is still installed in the ${global ? 'project' : 'global'} scope — remove that too: skills-atlas remove ${name} ${otherFlag}`));

package/src/commands/suggest.js

@@ -78,7 +78,7 @@ module.exports = async function suggest() {
           if (txt && !/^NONE\b/i.test(txt)) {
             const body = pending.source === 'fallback'
               ? txt // already a full digest for the main agent to judge
-              : `[Skills Atlas — capability gaps] ${txt}\nOffer this to the user only if it genuinely fits — verify with \`skills-atlas info <skill>\`, install with \`skills-atlas use <skill> --yes\`; otherwise stay silent.`;
+              : `[Skills Atlas — capability gaps] ${txt}\nOffer this to the user only if it genuinely fits — verify with \`skills-atlas info <skill>\`, install with \`skills-atlas use <skill> --yes --project\`; otherwise stay silent.`;
             emit(body + langHint(ap.replyLang));
             gapstate.touchNudge(gapstate.activitySignature(recent));
             writeState(file, state);
@@ -131,12 +131,12 @@ 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 { fire, candidates } = suggestCandidates(flatRows, prompt, { installed, suggested });
+    const { fire, candidates } = suggestCandidates(flatRows, prompt, { installed, suggested, feedback: require('../feedback').current() });
     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\`)`;
+      return `- ${c.skill}${uc ? ` — ${uc}` : ''}  (details: \`skills-atlas info ${c.skill}\` · use now: \`skills-atlas use ${c.skill} --yes --project\`)`;
     }).join('\n');
     emit(
       `[Skills Atlas autopilot] The user may be doing something one of these installable agent ` +
@@ -144,9 +144,10 @@ module.exports = async function suggest() {
       `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 ` +
+      `then let them choose — activate it now (\`skills-atlas use <skill> --yes --project\` 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 ` +
+      `do the task yourself; if they ask to never suggest it again, run \`skills-atlas feedback dismiss <skill>\`. ` +
+      `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.` + langHint(ap.replyLang));
     state.lastSuggestedCount = state.count;

package/src/feedback.js

@@ -0,0 +1,86 @@
+// Local suppression memory for the autopilot. Two scopes, because the two signals
+// mean different things:
+//
+//   • dismiss  — you explicitly said "never suggest this skill"        → GLOBAL table
+//   • removed  — you removed a project-scoped skill you'd installed     → PROJECT table
+//
+// A dismiss is a deliberate, blanket "no", so it applies everywhere. A removal is
+// contextual ("done with it here") — it must NOT leak to other projects, so it lives
+// in a per-project table keyed by the project root. The LATEST action per skill wins:
+// installing a skill clears both its global dismiss and this project's removal.
+//
+// All local; project tables live under the cache (keyed by path hash), never in the
+// repo, so personal suppression is never committed. Nothing is sent anywhere.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const MAX_EVENTS = 500;
+
+function baseDir() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'skills-atlas');
+}
+function globalFile() { return path.join(baseDir(), 'feedback.json'); }
+function projectFile(root) {
+  const key = crypto.createHash('sha1').update(path.resolve(root || process.cwd())).digest('hex').slice(0, 16);
+  return path.join(baseDir(), 'projects', `${key}.json`);
+}
+
+function readStore(file) {
+  try { const s = JSON.parse(fs.readFileSync(file, 'utf8')); if (!Array.isArray(s.events)) s.events = []; return s; }
+  catch { return { events: [] }; }
+}
+function writeStore(file, s) {
+  try { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify(s)); } catch { /* best-effort */ }
+}
+function append(file, skill, signal) {
+  if (!skill || !signal) return;
+  const s = readStore(file);
+  s.events.push({ skill, signal, at: new Date().toISOString() });
+  if (s.events.length > MAX_EVENTS) s.events = s.events.slice(-MAX_EVENTS);
+  writeStore(file, s);
+}
+
+// Pure: skills whose MOST RECENT action in this store is the suppressing signal.
+// (An 'accepted' afterwards clears it — you installed it, so you changed your mind.)
+function suppressedFrom(events, suppressSignal) {
+  const latest = new Map();
+  for (const e of events || []) {
+    if (!e || !e.skill) continue;
+    const prev = latest.get(e.skill);
+    if (!prev || Date.parse(e.at) >= Date.parse(prev.at)) latest.set(e.skill, e);
+  }
+  const out = new Set();
+  for (const [skill, e] of latest) if (e.signal === suppressSignal) out.add(skill);
+  return out;
+}
+
+// --- writes ---
+function dismiss(skill) { append(globalFile(), skill, 'dismissed'); }              // explicit "never, anywhere"
+function removedInProject(skill, root) { append(projectFile(root), skill, 'removed'); } // "not in this project"
+function installed(skill, root) { append(globalFile(), skill, 'accepted'); append(projectFile(root), skill, 'accepted'); }
+
+// --- reads ---
+function globalDismissed() { return suppressedFrom(readStore(globalFile()).events, 'dismissed'); }
+function projectRemoved(root) { return suppressedFrom(readStore(projectFile(root)).events, 'removed'); }
+
+// Merged view for the autopilot hook, which runs in a project cwd: a skill is hidden
+// if it's globally dismissed OR removed in this project.
+function current(root) {
+  const global = globalDismissed();
+  const project = projectRemoved(root);
+  const suppressed = new Set([...global, ...project]);
+  return { suppressed, isSuppressed: s => suppressed.has(s), global, project };
+}
+
+function clear(root) { writeStore(globalFile(), { events: [] }); writeStore(projectFile(root), { events: [] }); }
+
+module.exports = {
+  globalFile, projectFile, readStore, writeStore,
+  dismiss, removedInProject, installed,
+  globalDismissed, projectRemoved, current, clear,
+};

package/src/search-core.js

@@ -270,10 +270,11 @@ function contentDf(rows) {
 // `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 } = {}) {
+function suggestCandidates(rows, prompt, { installed = new Set(), suggested = new Set(), feedback = null, limit = 5 } = {}) {
   const tokens = tokenize(lc(prompt));
   if (tokens.length < 2) return { fire: false, candidates: [], weak: false };
-  const taken = new Set([...installed, ...suggested]);
+  // `taken` also drops what you've dismissed or installed-then-removed — never re-suggest those.
+  const taken = new Set([...installed, ...suggested, ...(feedback ? feedback.suppressed : [])]);
   const info = segmentDf(rows);
 
   // 1. name anchors — ONLY contentful (non-generic) name words count, weighted by
@@ -365,6 +366,9 @@ function suggestCandidates(rows, prompt, { installed = new Set(), suggested = ne
     anchors.some(a => a.strong >= 2 || a.specific >= 1) ||
     contentAnchors.some(contentQualifies)
   );
+  // NB: feedback only SUPPRESSES (via `taken` above) — that changes which skills make
+  // the shortlist. We deliberately don't reorder the final ≤5: Claude reads all of them
+  // and picks by fit, so reordering them would do nothing.
   return { fire, candidates: out.slice(0, limit), weak };
 }