skills-atlas-cli 0.9.1 → 0.11.0

package/bin/skills.js

@@ -16,7 +16,9 @@ const suggest = require('../src/commands/suggest');
 const hook = require('../src/commands/hook');
 const gaps = require('../src/commands/gaps');
 const gapAnalyze = require('../src/commands/gap-analyze');
+const craft = require('../src/commands/craft');
 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 +26,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, craft, prune, feedback, update, categories, list, registry, mcp };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -48,7 +50,9 @@ 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)
+  craft              codify a workflow you keep repeating into a new local skill (Claude drafts it)
   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.1",
+  "version": "0.11.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/craft.js

@@ -0,0 +1,53 @@
+// `skills-atlas craft` — feature ②: codify the user's OWN repeated workflow into a
+// new local SKILL.md. Run it in Claude Code: it hands the MAIN agent the detected
+// pattern + fuller evidence + a hardened authoring instruction, and the agent drafts
+// ./.claude/skills/<name>/SKILL.md for the user to review. It writes nothing itself.
+'use strict';
+
+const { parse } = require('../args');
+const transcripts = require('../transcripts');
+const gapstate = require('../gapstate');
+const gaps = require('./gaps');
+const registry = require('../registry');
+const { dim, langHint } = require('../format');
+
+const HELP = `usage: skills-atlas craft
+
+Codify a multi-step workflow you keep repeating into a new local skill — distilled
+from your OWN steps, written by Claude for you to review. Run it inside Claude Code.
+Reads your local transcripts; nothing is stored or sent. It writes nothing itself —
+it hands Claude an instruction; Claude drafts ./.claude/skills/<name>/SKILL.md, and
+only if your workflow carries a real user-specific delta (otherwise it declines).
+
+  craft        draft a skill from the workflow the autopilot flagged (or recent activity)
+  --json       print the detected pattern + evidence as JSON
+  --show       alias for the default (print the instruction)`;
+
+module.exports = async function craftCmd(argv) {
+  const { values } = parse(argv, ['json', 'show']);
+  if (values.help) { console.log(HELP); return; }
+
+  const recent = transcripts.recentPrompts({ max: 30 });
+  const pending = gapstate.readCraft();
+  const pattern = pending && pending.pattern
+    ? pending.pattern
+    : '(no pre-detected pattern — infer the user\'s repeated multi-step procedure from the evidence below; if there is no genuine user-specific delta, do NOT write a skill, per the gate.)';
+
+  if (values.json) {
+    console.log(JSON.stringify({
+      pattern: pending ? pending.pattern : null,
+      fromAutopilot: !!pending,
+      evidence: gaps.craftEvidence(recent),
+    }, null, 2));
+    return;
+  }
+
+  if (!recent.length) {
+    console.log(dim('no recent activity to craft from — use Claude Code for a while, then run this in a session.'));
+    return;
+  }
+
+  // Surfaced → consume it so the same pattern isn't offered again.
+  if (pending) gapstate.clearCraft();
+  console.log('\n' + gaps.craftInstruction(pattern, recent) + langHint(registry.getAutopilot().replyLang));
+};

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/gap-analyze.js

@@ -7,6 +7,9 @@
 'use strict';
 
 const { spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { parse } = require('../args');
 const { loadData } = require('../data');
 const { buildIndices } = require('../index-build');
@@ -21,6 +24,17 @@ const { dim, green } = require('../format');
 const CLAUDE_BIN = process.env.SKILLS_ATLAS_CLAUDE_BIN || 'claude';
 const TIMEOUT_MS = Number(process.env.SKILLS_ATLAS_GAP_TIMEOUT_MS) || 90000;
 
+// Project + global CLAUDE.md, lightly, so the detector's Gate 4 ("already covered by
+// a rule?") is real — the small model can't read the filesystem itself.
+function readClaudeMd() {
+  let out = '';
+  for (const f of [path.join(process.cwd(), 'CLAUDE.md'), path.join(os.homedir(), '.claude', 'CLAUDE.md')]) {
+    try { out += fs.readFileSync(f, 'utf8') + '\n'; } catch { /* none here */ }
+    if (out.length > 1200) break;
+  }
+  return out.slice(0, 1200);
+}
+
 function gather() {
   const recent = transcripts.recentPrompts({ max: 20 });
   const gs = gapstate.read();
@@ -31,7 +45,7 @@ function gather() {
   for (const s of fsu.scopesFor({})) for (const e of manifest.list(s.root)) installed.add(e.skill);
   const candidates = gaps.candidatePool(flatRows, recent, { installed, dismissed });
   const ap = registry.getAutopilot();
-  return { recent, dismissed, candidates, model: ap.gapModel, lang: ap.replyLang };
+  return { recent, dismissed, candidates, installed: [...installed], claudeMd: readClaudeMd(), model: ap.gapModel, lang: ap.replyLang };
 }
 
 // Run `claude -p --model <model>` with the prompt on stdin. Reuses Claude Code's
@@ -76,7 +90,7 @@ module.exports = async function gapAnalyze(argv) {
       if (values.show || values.once) console.error(dim(`not enough recent activity (${g.recent.length} < 8) — nothing to analyze.`));
       return;
     }
-    const prompt = gaps.analysisPrompt(g.recent, g.candidates, g.dismissed, g.lang);
+    const prompt = gaps.analysisPrompt(g.recent, g.candidates, g.dismissed, g.lang, { installed: g.installed, claudeMd: g.claudeMd });
 
     if (values.show) {
       console.log(dim(`# would run: ${CLAUDE_BIN} -p --model ${g.model}   (prompt piped on stdin)\n`));
@@ -86,8 +100,22 @@ module.exports = async function gapAnalyze(argv) {
 
     const r = await runClaude(prompt, g.model);
     if (r.ok) {
-      gapstate.writePending({ text: r.text, source: g.model });
-      if (values.once) console.log(`${green('✓')} ${g.model} →\n${r.text}`);
+      if (/^CRAFT:/i.test(r.text)) {
+        // A craftable workflow. Suppress if we already surfaced this exact pattern
+        // recently (don't re-nag — the Cursor failure); otherwise stash it for `craft`.
+        const fp = gapstate.craftFingerprint(r.text);
+        if (gapstate.craftOnCooldown(fp)) {
+          gapstate.writePending({ text: 'NONE', source: g.model });
+          if (values.once) console.error(dim('CRAFT matches a pattern surfaced within ~7d — staying silent (no re-nag).'));
+        } else {
+          gapstate.writeCraft({ line: r.text, pattern: r.text.replace(/^CRAFT:\s*/i, '').split('|')[0].trim(), fp });
+          gapstate.writePending({ text: r.text, source: g.model });
+          if (values.once) console.log(`${green('✓')} ${g.model} →\n${r.text}`);
+        }
+      } else {
+        gapstate.writePending({ text: r.text, source: g.model });
+        if (values.once) console.log(`${green('✓')} ${g.model} →\n${r.text}`);
+      }
     } else {
       // fail-open: stash the local inline digest so the hook still surfaces SOMETHING
       // (the previous behavior, just one tick later) instead of going silent.

package/src/commands/gaps.js

@@ -34,6 +34,7 @@ const INSTRUCTION = dismissed =>
   ` If nothing clearly recurs, say there are no gaps.`;
 
 const { runSearch } = require('../search-core');
+const craftPrompts = require('../craft-prompts');
 
 // Lexical recall over the AGGREGATED recent activity → candidate skills the user
 // hasn't installed. The signal is stronger than any single prompt; the model
@@ -61,17 +62,30 @@ function digest(recent, dismissed, candidates = []) {
   return `[Skills Atlas — capability gaps] The user's recent requests (${recent.length} over ~${days} day(s), newest first):\n${activityLines(recent)}${candidateLines(candidates)}\n\n${INSTRUCTION(dismissed)}`;
 }
 
-// The prompt handed to the small BACKGROUND model. It returns NONE or one line.
-function analysisPrompt(recent, candidates, dismissed, lang) {
+// The prompt handed to the small BACKGROUND model. Adversarially hardened (see
+// craft-prompts.js). Emits exactly one of NONE / EXISTING <skill> / CRAFT: <pattern>.
+// `extra.installed` (names) and `extra.claudeMd` (excerpt) make Gate 4 real at
+// detection time — the small model can't see the filesystem, so we feed it in.
+function analysisPrompt(recent, candidates, dismissed, lang, extra = {}) {
   const langName = lang === 'zh' ? '简体中文' : 'English';
-  return 'You look at a developer\'s recent activity and spot ONE recurring kind of work that an installable "skill" would help with but they haven\'t set up.\n\n' +
-    `Recent requests (newest first):\n${activityLines(recent)}\n` +
-    (candidates.length ? `\nInstallable catalog skills that may be relevant:\n${candidates.map(c => `- ${c.skill}: ${c.use}`).join('\n')}\n` : '') +
-    (dismissed.length ? `\nAlready dismissed (never suggest): ${dismissed.join(', ')}\n` : '') +
-    `\nIf there is a CLEAR recurring need that ONE of the listed skills covers, reply with a single line in ${langName}:\n` +
-    '  <skill-name> — one short sentence naming the recurring pattern (with rough frequency) and why that skill helps.\n' +
-    'Otherwise reply with exactly: NONE\n' +
-    'Output ONLY that one line (or NONE), nothing else.';
+  return craftPrompts.detectionPrompt({
+    activity: activityLines(recent),
+    candidates: candidates.length ? candidates.map(c => `- ${c.skill}: ${c.use}`).join('\n') : '(none matched)',
+    dismissed: dismissed.length ? dismissed.join(', ') : '(none)',
+    installed: (extra.installed && extra.installed.length) ? extra.installed.join(', ') : '(none)',
+    claudeMd: extra.claudeMd ? String(extra.claudeMd).replace(/\s+/g, ' ').trim().slice(0, 800) : '(none found)',
+    lang: langName,
+  });
+}
+
+// Fuller per-prompt evidence for `craft` — detection truncates each prompt to ~100
+// chars, but the corrections that prove the user's delta need more room (~400).
+function craftEvidence(recent, { chars = 400, max = 24 } = {}) {
+  return recent.slice(0, max).map(r => `  - ${r.text.replace(/\s+/g, ' ').trim().slice(0, chars)}`).join('\n');
+}
+// The instruction injected into the MAIN agent when the user runs `craft`.
+function craftInstruction(pattern, recent, opts) {
+  return craftPrompts.craftPrompt({ pattern, evidence: craftEvidence(recent, opts) });
 }
 
 module.exports = async function gapsCmd(argv) {
@@ -112,3 +126,5 @@ module.exports = async function gapsCmd(argv) {
 module.exports.candidatePool = candidatePool;
 module.exports.digest = digest;
 module.exports.analysisPrompt = analysisPrompt;
+module.exports.craftEvidence = craftEvidence;
+module.exports.craftInstruction = craftInstruction;

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

@@ -76,9 +76,17 @@ module.exports = async function suggest() {
           gapstate.clearPending();
           const txt = (pending.text || '').trim();
           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 --project\`; otherwise stay silent.`;
+            let body;
+            if (/^CRAFT:/i.test(txt)) {
+              // Feature ②: a craftable workflow no skill covers. Restrained, decline-easy offer.
+              const pat = txt.replace(/^CRAFT:\s*/i, '').split('|')[0].trim();
+              body = `[Skills Atlas autopilot] The user keeps doing a multi-step workflow that no installed or catalog skill covers: ${pat}. ` +
+                `ONLY if this genuinely fits what they're actually doing, offer once — in one easy-to-decline line — to codify it into a reusable skill built from their OWN steps: they can run \`skills-atlas craft\` and you'll draft a SKILL.md from their workflow for them to review (nothing is written until they run it; it's a draft they keep or delete). If it doesn't clearly fit, say nothing about this at all.`;
+            } else {
+              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 --project\`; otherwise stay silent.`;
+            }
             emit(body + langHint(ap.replyLang));
             gapstate.touchNudge(gapstate.activitySignature(recent));
             writeState(file, state);
@@ -131,7 +139,7 @@ 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 => {
@@ -146,7 +154,8 @@ module.exports = async function suggest() {
       `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 --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/craft-prompts.js

@@ -0,0 +1,136 @@
+// The two model-facing prompts for feature ② "craft" (generative gap-filling),
+// hardened by an adversarial multi-agent pass (drafts → critique → synthesis).
+//
+//  • DETECTION  — handed to the small background model (gap-analyze). Reads the user's
+//                 recent prompts + matched catalog skills and emits exactly one of
+//                 NONE / EXISTING <skill> / CRAFT: <pattern> | DELTA: <quoted artifact>.
+//                 Biased hard toward NONE; the firewall is a QUOTABLE user-specific delta.
+//  • CRAFT_INSTRUCTION — injected into the MAIN agent when the user runs `skills-atlas
+//                 craft`. Distills the user's OWN repeated procedure into one SKILL.md,
+//                 self-contained, delta-only, draft-for-review, never auto-active.
+//
+// Placeholders are filled by split/join (no regex, so `$` in the activity text is safe).
+'use strict';
+
+const DETECTION = `You read a developer's recent Claude Code requests and decide whether ONE recurring kind of work is worth acting on. Your default answer is NONE, and it is the right answer most of the time. Only an unmistakable, repeated, concrete signal overrides that default. When in any doubt, output NONE. It is far better to MISS a real pattern than to NAG the user with a weak, generic, or one-off one.
+
+Recent requests (newest first):
+{{ACTIVITY}}
+
+Installable catalog skills that lexically matched this activity (these MAY be relevant — judge for yourself; lexical matching is shallow and may miss or misfire):
+{{CANDIDATES}}
+
+Already dismissed (never suggest and never craft these, or anything equivalent to them): {{DISMISSED}}
+Already installed (a need one of these already covers is NOT uncovered — never CRAFT or recommend these): {{INSTALLED}}
+Your project CLAUDE.md rules (excerpt; if a rule here already governs the procedure, it is covered → not CRAFT): {{CLAUDEMD}}
+
+WHAT YOU SEE, AND ITS LIMITS. The list above is ONLY the user's own typed prompts, each truncated to ~100 characters, with no timestamps and no replies from the assistant. You therefore CANNOT see the assistant's answers, tool calls, diffs, or most of the corrections the user actually made. Do not pretend to. A task being phrased similarly several times is just how a routine recurring task looks — it is NOT, by itself, evidence that the user does it in a special way.
+
+You output EXACTLY ONE of three verdicts and nothing else:
+- NONE — nothing clearly recurs, the signal is too thin, or the recurring work has no user-specific, codifiable procedure. This is the common case.
+- EXISTING — a real recurring need that ONE of the listed catalog skills already covers; the user just hasn't installed it.
+- CRAFT — a recurring multi-step PROCEDURE the user performs in their OWN particular, visible way, that NO listed catalog skill covers, worth distilling into a new local skill from their actual workflow.
+
+=== HARD PRECONDITIONS (if any fails → NONE) ===
+- At least THREE separate, substantive requests in the list are clearly the SAME kind of work. Ignore filler and continuation prompts ("yes", "ok", "continue", "go on", "run it", "next", "thanks") and anything under ~5 words when counting — they are not independent requests.
+- Those three must look spread across different occasions, not one continuous back-and-forth on a single task or feature. You have no timestamps, so if the three reasonably read as one focused session iterating on one thing, treat it as a single occasion → NONE.
+- The evidence must be concrete in the text above. If you are inferring the pattern from one request plus imagination, or guessing what the user "probably" does off-screen, output NONE.
+- If the activity is sparse, generic, or a scatter of unrelated tasks, output NONE.
+
+=== PREFER EXISTING OVER CRAFT ===
+An installable catalog skill beats authoring a new one. If a listed catalog skill plausibly covers the recurring need, choose EXISTING. Only consider CRAFT when no listed skill fits.
+
+=== THE FOUR GATES FOR CRAFT — ALL must hold, or do NOT emit CRAFT ===
+
+GATE 1 — RECURS. The same kind of work appears on 3+ distinct, substantive occasions (per the preconditions). Frequency is NECESSARY but NOT sufficient: it only proves the TOPIC recurs, never that there is anything user-specific to codify.
+
+GATE 2 — IS A PROCEDURE. Multi-step work with an order or set of conventions — a workflow, checklist, or pipeline — NOT a single-shot task and NOT a standing one-line preference.
+  - A single action is not a procedure: "fix this typo", "rename X", "explain this error", "translate this", "add an index". Reject.
+  - A single standing preference is not a procedure: "always use tabs", "prefer named exports", "reply in Chinese", "PR titles start with the ticket id". That is a CLAUDE.md rule with no steps, NOT a skill. Reject → NONE.
+  Test: "If I wrote this down, would it be an ORDERED list of several steps the user repeats, or just one instruction?" Only the ordered list passes. A multi-step task is still necessary-but-far-from-sufficient — most multi-step work is generic and dies at Gate 3.
+
+GATE 3 — CARRIES A VISIBLE, USER-SPECIFIC DELTA (the firewall; apply it ruthlessly). The procedure must encode something a competent assistant would NOT already do by default — the user's OWN conventions: a named command/script/flag, a specific file path or layout, a fixed format or checklist they impose, a non-obvious ordering constraint, or a correction they explicitly keep re-issuing ("again", "like before", "not like that — do it our way", "you forgot X", "always do X first", "use OUR script/format").
+  You may claim a delta ONLY if you can QUOTE the specific token(s) from the requests above that prove it — an exact command, filename, flag, path, format name, or explicit correction, appearing across the recurring requests. The delta must be QUOTABLE, not inferred from the topic.
+  A REPEATED INSTRUCTION IS NOT, BY ITSELF, A DELTA. Because you see only the user's prompts (never the assistant's replies), a routine task naturally gets phrased the same way each time; that sameness is not a correction and not a convention. If the recurring steps are ones any competent assistant already performs (validate → handler → test, lint → test → commit, reproduce → fix → re-run, write up → down → migrate, write tests, run the linter, use clear names, handle errors), the delta is ZERO → NONE. A vague topic ("they do a lot of testing", "a deployment workflow") is not a delta.
+  ANTI-CONFABULATION: You are forbidden from inventing a delta to justify CRAFT. If you cannot quote the evidence that proves a user-specific delta, the answer is NONE — even when the work clearly recurs and is multi-step. Recurrence + ordered steps WITHOUT a quotable delta = NONE. If your CRAFT line would contain only generic verbs (add / update / write / test / deploy / fix) and category nouns, output NONE. Specificity test: if the delta would survive find-replacing this project's name with any other project's, it is generic → NONE.
+
+GATE 4 — NOT ALREADY COVERED. No listed catalog skill fits, nothing in "Already installed" covers it, and no CLAUDE.md rule above already handles it. An ABSENT candidate is NOT proof of "uncovered": lexical matching is shallow and may have missed a covering skill. For a common engineering task (testing, PR prep, releasing, migrations, adding endpoints, debugging), assume a catalog or built-in capability likely covers it and prefer EXISTING or NONE. Treat it as genuinely uncovered ONLY when the procedure is idiosyncratic to THIS user — which is exactly what Gate 3 must already have proven.
+
+If all four gates hold AND no catalog skill fits → CRAFT. In every other case → NONE.
+
+=== OUTPUT — emit EXACTLY ONE line, nothing before or after, no preamble, no markdown, no second line. Write the line (other than the literal word NONE) in {{LANG}}. ===
+
+NONE
+  — or —
+EXISTING <skill-name> — one line: the recurring pattern + rough frequency (e.g. "~4 times") + why that listed catalog skill (named verbatim) covers it
+  — or —
+CRAFT: <one line naming the uncovered recurring multi-step procedure + its rough frequency as evidence> | DELTA: <the concrete user-specific thing it would encode, quoting the exact command / path / flag / format / correction you saw in the requests above>
+
+Rules for the line:
+- EXISTING <skill-name> must be one of the listed catalog skills, verbatim.
+- CRAFT names the user's ACTUAL procedure, not a topic area, and you must be able to fill DELTA with a real quoted artifact. If you cannot, fall back to NONE.
+- When the four gates are not ALL clearly satisfied, output NONE.`;
+
+const CRAFT_INSTRUCTION = `[Skills Atlas — craft a skill from your own repeated workflow]
+
+A background detector flagged a recurring multi-step procedure in the user's recent Claude Code activity that no installed or catalog skill appears to cover, and the user has now run \`skills-atlas craft\`. Your job is to draft a local project skill that codifies THE USER'S OWN procedure — self-evolution from their actual usage. You are distilling what THEY already do; you are NOT authoring a generic best-practice guide for a topic. The detector is deliberately conservative but works from thin evidence (the user's prompts, truncated, no replies); YOU have the real project in front of you, so part of your job is to VETO it when the signal doesn't hold up.
+
+DETECTED PATTERN:
+{{PATTERN}}
+
+RELEVANT RECENT-ACTIVITY EVIDENCE (the user's own requests that show this procedure, newest first):
+{{EVIDENCE}}
+
+=== STEP 1 — EXTRACT THE DELTA, OR BAIL (do this before writing anything) ===
+Find what makes THIS user's procedure non-obvious. Produce a concrete list of the user-specific artifacts: their exact commands, scripts, flags, file paths, naming conventions, ordering constraints, fixed formats/checklists, and especially any instruction they kept RE-ISSUING because the generic approach was wrong. Quote them from the evidence.
+
+To ground this in reality rather than guessing, you MAY first read existing project files the evidence points at — ./CLAUDE.md, ~/.claude/CLAUDE.md, ./.claude/skills/*/SKILL.md, a Makefile/justfile, the test directory, an existing handler/migration the user keeps editing. Read only; write nothing except the one SKILL.md. Use these to confirm the user's ACTUAL conventions instead of inventing plausible ones.
+
+Then apply the hard gate. Proceed to write ONLY if ALL hold:
+1. The evidence shows the same multi-step procedure on more than one distinct occasion.
+2. It is a genuine ordered procedure, not a single-shot task and not a single standing preference. If the only real signal is ONE standing rule (e.g. "regenerate the spec with \`make openapi\`, never the IDE plugin"), that belongs in CLAUDE.md, NOT a skill — say so and write nothing. Never pad one rule with generic steps to make it "skill-shaped".
+3. You can quote at least TWO specific evidence lines (or grounding files) carrying the user's particular convention/format/flag/path/correction — something beyond how any competent assistant would already do this task. If that list is empty or only generic steps, STOP.
+4. Nothing already installed (./.claude/skills/, ~/.claude/skills/), no listed catalog skill, and no CLAUDE.md rule already does this. Before choosing a name, list ./.claude/skills/* ; if a sibling already covers it, stop.
+
+If any check fails, write NO file. Say in one line what you found and why it's not skill-worthy — e.g. "The pattern recurs but I can't see anything specific to how YOU do it — there's no delta worth a skill yet; tell me your conventions, or this may just belong in CLAUDE.md." Default to stopping: a missing file is the correct, safe outcome, and the user running \`craft\` is NOT itself evidence a delta exists. A skill that restates common knowledge is a failure, not a deliverable.
+
+=== STEP 2 — CLARIFY ONLY IF GENUINELY AMBIGUOUS ===
+If the procedure is real but one key convention is unclear from the evidence and the files, ask the user ONE focused question, then write. Otherwise write directly — do not interrogate them.
+
+=== STEP 3 — WRITE THE SKILL.md ===
+Write exactly ONE file: ./.claude/skills/<name>/SKILL.md (create the folder). Touch nothing else; do not run git; do not install or enable anything. You are the author — do not depend on any external skill-creator. Follow Anthropic's skill conventions exactly.
+
+Frontmatter (YAML between --- fences, only these two keys):
+- name: lowercase-with-hyphens, <=64 chars, in GERUND / action form naming the procedure (e.g. running-release-checks, preparing-pr-descriptions). It MUST match the <name> folder.
+- description: third person, one or two sentences stating WHAT the skill does AND WHEN to use it, with concrete trigger terms drawn from the user's ACTUAL nouns in the evidence (their service/file/tool/format names), not the bare category word — so it auto-loads at the right moment. (e.g. "Runs the project's pre-release checklist. Use when cutting a release, tagging a version, or before publishing.")
+
+Body (Markdown — encode ONLY the user-specific delta):
+- Open with one line on when this applies.
+- Then the CORE: the user's ACTUAL procedure as a clear ORDERED workflow or checklist — their real steps, in their order, with their exact commands / paths / file names / flags / formats inlined verbatim from the evidence. Where the user kept correcting or re-instructing something, make that an explicit, prominent step — those corrections are the whole point.
+- If the user has a fixed output format or checklist, reproduce it as a template/code block exactly as they use it.
+- Briefly note WHICH repeated requests (or which grounding file) each convention came from, so the user can confirm you did not invent it.
+- End with a one-line provenance note, e.g.: "_Locally crafted by Skills Atlas, distilled from your own repeated workflow — review and edit freely; delete the folder to remove it._"
+
+HARD CONSTRAINTS — the firewall against correct-but-useless output:
+- Every numbered step MUST carry a user-specific token (a real command, path, flag, or named format). A step that is only a generic verb phrase ("write a test", "update the docs", "handle errors", "run the linter", "use clear names") must be DELETED — the assistant already does that by default. If, after deleting all generic steps, fewer than ~2 substantive delta-bearing steps remain, you do NOT have a skill — bail per Step 1.
+- Challenge every token. Assume the reader is already a capable agent who knows generic best practice; write only what is specific to THIS user and THIS procedure. Keep SKILL.md tight and well under ~500 lines; most crafted skills are far shorter.
+- Use progressive disclosure: push long reference material into a sibling file (one level deep) only if genuinely needed; most crafted skills are a single SKILL.md.
+- Do not invent conventions the user has not shown. If unsure whether a step is theirs or generic, leave it out or mark it clearly for them to confirm.
+
+=== STEP 4 — SHOW YOUR WORK ===
+Print the path you wrote and the full SKILL.md contents. Tell the user this is a DRAFT distilled from their own usage: review and edit it, it loads automatically next session, and deleting the folder discards it. In one line, state the specific user-delta you encoded (and where it came from) so they can sanity-check you captured the right thing. Do not commit it or take any further action unless they ask. Reply in the user's language.`;
+
+const fill = (tpl, map) =>
+  Object.keys(map).reduce((s, k) => s.split('{{' + k + '}}').join(map[k]), tpl);
+
+function detectionPrompt({ activity, candidates, dismissed, installed, claudeMd, lang }) {
+  return fill(DETECTION, {
+    ACTIVITY: activity, CANDIDATES: candidates, DISMISSED: dismissed,
+    INSTALLED: installed, CLAUDEMD: claudeMd, LANG: lang,
+  });
+}
+function craftPrompt({ pattern, evidence }) {
+  return fill(CRAFT_INSTRUCTION, { PATTERN: pattern, EVIDENCE: evidence });
+}
+
+module.exports = { DETECTION, CRAFT_INSTRUCTION, detectionPrompt, craftPrompt };

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

@@ -13,6 +13,7 @@ const { tokenize } = require('./search-core');
 // 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
+const CRAFT_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // ~7 d: never re-surface the SAME craft pattern
 
 function file() {
   const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
@@ -35,6 +36,28 @@ function writePending(p) { const s = read(); s.pending = { ...p, at: new Date().
 function clearPending() { const s = read(); delete s.pending; write(s); }
 function markAnalyze() { const s = read(); s.analyzeAt = new Date().toISOString(); write(s); }
 
+// --- CRAFT (feature ②): a detected, craftable workflow the user can codify. ---
+// Fingerprint the pattern (not the DELTA tail) so the same craft isn't re-nagged.
+function craftFingerprint(line) {
+  const core = String(line || '').replace(/^CRAFT:\s*/i, '').split('|')[0];
+  return tokenize(core.toLowerCase()).sort().slice(0, 12).join(' ');
+}
+// Was this exact craft pattern surfaced within the cooldown? (the Cursor-failure guard)
+function craftOnCooldown(fp, now = Date.now()) {
+  const lc = read().lastCraft;
+  return !!(lc && lc.fp === fp && now - Date.parse(lc.at) < CRAFT_COOLDOWN_MS);
+}
+// Stash the craftable pattern for the `craft` command, and remember we surfaced it.
+function writeCraft({ line, pattern, fp }) {
+  const s = read();
+  const at = new Date().toISOString();
+  s.craft = { line, pattern, at };
+  s.lastCraft = { fp, at };
+  write(s);
+}
+function readCraft() { return read().craft || null; }
+function clearCraft() { const s = read(); delete s.craft; write(s); }
+
 // 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) {
@@ -72,6 +95,7 @@ function shouldNudge(state, recent, now) {
 module.exports = {
   file, read, write, dismiss, isDismissed, touchNudge, clear,
   writePending, clearPending, markAnalyze,
+  craftFingerprint, craftOnCooldown, writeCraft, readCraft, clearCraft,
   activitySignature, signatureShifted, shouldNudge,
-  MIN_INTERVAL_MS, REFRESH_INTERVAL_MS,
+  MIN_INTERVAL_MS, REFRESH_INTERVAL_MS, CRAFT_COOLDOWN_MS,
 };

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