skills-atlas-cli 0.4.1 → 0.5.0

package/README.md

@@ -32,6 +32,29 @@ npm install -g skills-atlas-cli      # adds the `skills-atlas` command (alias: `
 
 Or run it without installing: `npx skills-atlas-cli search seo`
 
+## How you'll use it
+
+Three ways to reach the same catalog — pick whichever fits the moment:
+
+| Mode | Best when | Get going |
+|---|---|---|
+| **Manual** | you want to browse and grab skills yourself | `skills-atlas search <task>` → `skills-atlas use <skill>` |
+| **In Claude Code** | you'd rather just ask Claude in-conversation | install the [plugin](#in-claude-code), then describe your task |
+| **🤖 Autopilot** | you want the right skill to find *you* | `skills-atlas hook on` — Claude offers a fitting skill as you work |
+
+**60-second quickstart:**
+
+```bash
+npm install -g skills-atlas-cli
+skills-atlas search "stress test my launch plan"   # → pre-mortem tops the results
+skills-atlas use pre-mortem                         # install + activate now (prints its SKILL.md)
+skills-atlas hook on                                # optional — let the right skill find you from here on
+```
+
+`use` drops the skill into `~/.claude/skills/` and prints it for the task at hand; it
+auto-loads in new Claude Code sessions. With autopilot on, you don't even need to
+`search` — describe your task and Claude surfaces the skill if one fits.
+
 ## Usage
 
 ```bash
@@ -57,6 +80,10 @@ skills-atlas upgrade brainstorming             # re-fetch to latest (--all; won'
 skills-atlas remove brainstorming              # delete it
 skills-atlas doctor                            # health check: orphans, drift, license/script risks
 
+# 📦 Set up a whole project at once
+skills-atlas kit                               # detect this project & install the right skills for it
+skills-atlas sync                              # reproduce a project's kit (skills-atlas.kit.json)
+
 # 🌐 Catalog
 skills-atlas categories                        # the 20 top-level categories
 skills-atlas list marketing                    # skill groups within a category
@@ -67,6 +94,11 @@ skills-atlas update                            # pull the latest catalog
 `brainstorming → writing-plans → executing-plans → …`). `install <skill> --chain`
 installs the whole pipeline in one archive download, 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.
 
@@ -113,11 +145,12 @@ skills-atlas hook on      # enable    (skills-atlas hook off / status)
 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 — and
-if so offers to install + activate it. 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:
+if so, 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

package/bin/skills.js

@@ -9,6 +9,8 @@ const upgrade = require('../src/commands/upgrade');
 const remove = require('../src/commands/remove');
 const outdated = require('../src/commands/outdated');
 const doctor = require('../src/commands/doctor');
+const kit = require('../src/commands/kit');
+const sync = require('../src/commands/sync');
 const suggest = require('../src/commands/suggest');
 const hook = require('../src/commands/hook');
 const update = require('../src/commands/update');
@@ -17,7 +19,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, installed, upgrade, remove, outdated, doctor, suggest, hook, update, categories, list };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, update, categories, list };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -35,6 +37,8 @@ manage what you've installed:
   upgrade [skill]    re-fetch to the latest (--all; refuses to clobber local edits)
   remove <skill>     delete an installed skill
   doctor             health check: orphans, drift, missing SKILL.md, license/script risks
+  kit                set up the right skills for THIS project (detect + install)
+  sync               reproduce a project's kit from skills-atlas.kit.json
 
 autopilot (opt-in):
   hook on|off|status proactively suggest a skill in Claude when your prompt fits one

package/package.json

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

@@ -21,6 +21,8 @@ const ALL = {
   zh: { type: 'boolean' },
   all: { type: 'boolean' },
   inline: { type: 'boolean' },
+  archetype: { type: 'string' },
+  update: { type: 'boolean' },
   help: { type: 'boolean', short: 'h' },
 };
 

package/src/commands/hook.js

@@ -69,7 +69,13 @@ module.exports = async function hook(argv) {
   if (values.json) { console.log(JSON.stringify({ enabled: sub === 'on', settings: p })); return; }
   console.log(`${green('✓')} autopilot ${sub === 'on' ? 'enabled' : 'disabled'}  ${dim(p)}`);
   if (sub === 'on') {
-    console.log(dim('Claude now gets a one-line skill suggestion when your prompt strongly matches a catalog skill.'));
-    console.log(dim('needs `skills-atlas` on PATH (npm i -g skills-atlas-cli). turn off: skills-atlas hook off'));
+    console.log('\nHow it works: when what you ask lines up with a skill you don\'t have yet, Claude');
+    console.log('quietly gets a shortlist and — only if one truly fits — explains it and offers a choice:');
+    console.log(dim('  you:    "run a pre-mortem before we launch"'));
+    console.log(dim('  claude: "that\'s exactly what the pre-mortem skill does — it stress-tests your plan'));
+    console.log(dim('           before launch. use it now / see what it covers / skip?"'));
+    console.log(dim('\nIt stays silent on greetings and generic asks, never repeats a skill, and Claude makes'));
+    console.log(dim('the final call on relevance. Nothing leaves your machine.'));
+    console.log(dim('\nneeds `skills-atlas` on PATH (npm i -g skills-atlas-cli).  turn off: skills-atlas hook off'));
   }
 };

package/src/commands/install.js

@@ -275,12 +275,16 @@ module.exports = async function install(argv) {
   if (values.inline) {
     const body = readSkillMd(result.dest);
     if (body) {
-      console.log('\n' + dim('─── SKILL.md (active for this task — follow it now) ───'));
+      console.log('\n' + dim('─── SKILL.md — the skill\'s own instructions; apply them to the task now ───'));
       console.log(body.trim());
       console.log(dim('─── end SKILL.md ───'));
     }
-    console.log(dim('\n(the folder is also installed for future sessions)'));
+    console.log(`\n${green('✓')} ${bold(skill)} is now active — use the instructions above for the task at hand.`);
+    console.log(dim(`  installed at ${fsu.tildify(result.dest)} (auto-loads in new sessions) · what it does: skills-atlas info ${skill} · remove: skills-atlas remove ${skill}`));
   } else {
-    console.log(dim('\nStart a new Claude Code session to load the skill, then invoke it by name.'));
+    console.log(`\n${bold(skill)} is installed but not loaded yet. To use it:`);
+    console.log(dim(`  • now, in this session:  skills-atlas use ${skill}`));
+    console.log(dim('  • or start a new Claude Code session — it auto-loads from ~/.claude/skills/'));
+    console.log(dim(`  what it does: skills-atlas info ${skill} · remove: skills-atlas remove ${skill}`));
   }
 };

package/src/commands/kit.js

@@ -0,0 +1,136 @@
+// `skills-atlas kit` — detect the project's archetype(s), propose a curated skill
+// kit (core dev workflow + add-ons), install to project scope after confirmation,
+// and write a committable skills-atlas.kit.json. Reuses installer/manifest/index.
+'use strict';
+
+const path = require('path');
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, vendorsFor, skillDocPath } = require('../index-build');
+const { installFolder } = require('../installer');
+const fsu = require('../fsutil');
+const km = require('../kitmanifest');
+const { detect } = require('../detect');
+const { buildKitPlan, ARCHETYPE_NAMES } = require('../kits');
+const { confirm } = require('../prompt');
+const { bold, dim, green, cyan } = require('../format');
+
+const HELP = `usage: skills-atlas kit [options]
+
+Detect this project's type, propose a curated skill kit, install it to
+./.claude/skills/, and write a committable skills-atlas.kit.json.
+
+options:
+  --archetype <name>  override detection (${ARCHETYPE_NAMES.join(', ')})
+  --global            install to ~/.claude/skills/ instead of the project
+  --yes               install the proposed kit without prompting
+  --dry-run           show the proposed kit; write nothing
+  --json              machine-readable output`;
+
+module.exports = async function kit(argv) {
+  const { values } = parse(argv, ['global', 'project', 'yes', 'dry-run', 'json', 'archetype']);
+  if (values.help) { console.log(HELP); return; }
+
+  const projectRoot = process.cwd();
+  const global = Boolean(values.global);            // kit defaults to PROJECT scope
+  const targetRoot = fsu.installTargetDir({ global });
+
+  // 1. detect (or honor --archetype)
+  let archetypes, signals;
+  if (values.archetype) {
+    if (!ARCHETYPE_NAMES.includes(values.archetype)) {
+      console.error(`unknown archetype '${values.archetype}'. known: ${ARCHETYPE_NAMES.join(', ')}`);
+      process.exitCode = 1; return;
+    }
+    archetypes = [values.archetype]; signals = [`--archetype ${values.archetype}`];
+  } else {
+    ({ archetypes, signals } = detect(projectRoot));
+  }
+
+  // 2. resolve catalog + currently-installed set, build the plan
+  const { data } = loadData({ quiet: values.json });
+  const idx = buildIndices(data);
+  const installed = new Set(require('../manifest').list(targetRoot).map(e => e.skill));
+  const plan = buildKitPlan(archetypes, installed);
+
+  // resolve each skill to an installable source (skip ones with no folder)
+  const items = [];
+  for (const s of plan.skills) {
+    const chosen = vendorsFor(idx.skillIndex, s.name)[0];
+    const docPath = chosen && skillDocPath(chosen.vendor, s.name);
+    items.push({ ...s, chosen, docPath, installable: Boolean(docPath) });
+  }
+  const installable = items.filter(i => i.installable && !i.installed);
+
+  // human proposal (machine mode prints one JSON object at the end instead)
+  if (!values.json) {
+    console.log(`\nDetected: ${bold(archetypes.join(' + '))}  ${dim(signals.join('; '))}`);
+    console.log(`Proposed kit — ${installable.length} new skill(s) → ${fsu.tildify(targetRoot)}\n`);
+    let group = null;
+    for (const i of items) {
+      if (i.group !== group) { group = i.group; console.log(`  ${group === 'core' ? 'core dev workflow' : group}`); }
+      const mark = i.installed ? dim('✓ installed') : i.installable ? '' : dim('(whole-repo only — skipped)');
+      console.log(`    • ${i.name.padEnd(26)} ${dim(i.reason)} ${mark}`);
+    }
+  }
+  const proposal = { archetypes, scope: global ? 'global' : 'project',
+    skills: items.map(i => ({ name: i.name, group: i.group, installed: i.installed, installable: i.installable })) };
+
+  if (values['dry-run']) {
+    if (values.json) console.log(JSON.stringify(proposal, null, 2));
+    else console.log(dim('\n(dry run — nothing written)'));
+    return;
+  }
+  if (!installable.length) {
+    if (values.json) console.log(JSON.stringify({ ...proposal, manifest: null, installedNow: [], failed: [] }, null, 2));
+    else console.log(green('\n✓ nothing to install — kit already satisfied.'));
+    return;
+  }
+
+  if (!values.yes && !values.json) {
+    const ok = await confirm(`\nInstall ${installable.length} skill(s) and write ${km.FILE}?`, true);
+    if (!ok) { console.log('aborted.'); return; }
+  }
+
+  // 3. install (best-effort, like the chain installer)
+  const recorded = [];
+  const installedNow = [], failed = [];
+  for (const i of installable) {
+    const v = i.chosen.vendor, src = i.chosen.source;
+    const dest = path.join(targetRoot, i.name);
+    try {
+      const r = await installFolder({
+        author: v.author || src.author, repo: v.repo || src.repo,
+        branch: v.default_branch || src.default_branch || 'main',
+        docPath: i.docPath, dest, targetRoot, skillName: i.name,
+        source: src.name, group: i.chosen.row && i.chosen.row.group, category: i.chosen.row && i.chosen.row._cat,
+      });
+      if (!values.json) console.log(`  ${green('✓')} ${i.name} ${dim(`(${r.fileCount} files)`)}`);
+      recorded.push({ name: i.name, source: src.name, ref: r.branchUsed, hash: r.hash, group: i.group });
+      installedNow.push(i.name);
+    } catch (e) {
+      if (!values.json) console.log(`  ${dim('✗ ' + i.name + ' — ' + e.message)}`);
+      failed.push({ name: i.name, error: e.message });
+    }
+  }
+
+  // include already-installed kit members in the manifest too (so it's complete)
+  for (const i of items.filter(x => x.installed)) {
+    const rec = require('../manifest').read(targetRoot).skills[i.name] || {};
+    recorded.push({ name: i.name, source: rec.source || null, ref: rec.branch || null, hash: rec.hash || null, group: i.group });
+  }
+
+  // 4. write the committable kit manifest
+  const manifest = { version: 1, archetypes, scope: global ? 'global' : 'project', skills: recorded };
+  km.write(projectRoot, manifest);
+  if (failed.length) process.exitCode = 1; // surface partial/total install failure to callers/CI
+
+  if (values.json) {
+    console.log(JSON.stringify({ ...proposal, manifest: km.FILE, installedNow, failed }, null, 2));
+  } else {
+    console.log(`\n${green('✓')} kit ready — ${recorded.length} skill(s); wrote ${cyan(km.FILE)}`);
+    if (failed.length) console.log(dim(`  ${failed.length} failed to install — see above.`));
+    console.log(dim(`  teammates can reproduce it with: skills-atlas sync`));
+    console.log(dim('  start a new Claude Code session to load the skills.'));
+  }
+};

package/src/commands/suggest.js

@@ -63,16 +63,19 @@ module.exports = async function suggest() {
 
     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}` : ''}  (install+activate: \`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\`)`;
     }).join('\n');
     const ctx =
       `[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` +
-      `If one clearly fits, briefly offer it and (with the user's ok) install it via its command. ` +
-      `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 — do not mention this hook, these skills, or that a suggestion was made.`;
+      `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 ` +
+      `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 } }));
 
     state.lastSuggestedCount = state.count;

package/src/commands/sync.js

@@ -0,0 +1,91 @@
+// `skills-atlas sync` — read skills-atlas.kit.json and install/upgrade the project
+// to match it. Idempotent; for teammates and CI. Reuses installer + drift guard.
+'use strict';
+
+const path = require('path');
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, vendorsFor, skillDocPath } = require('../index-build');
+const { installFolder } = require('../installer');
+const fsu = require('../fsutil');
+const km = require('../kitmanifest');
+const { green, dim, cyan } = require('../format');
+
+const HELP = `usage: skills-atlas sync [options]
+
+Read skills-atlas.kit.json and install/upgrade this project's skills to match it.
+
+options:
+  --global    sync to ~/.claude/skills/ instead of the project
+  --force     overwrite skills with local edits
+  --update    re-fetch every skill to latest and rewrite the manifest
+  --dry-run   show what would change; write nothing
+  --json      machine-readable output`;
+
+module.exports = async function sync(argv) {
+  const { values } = parse(argv, ['global', 'project', 'force', 'update', 'dry-run', 'json']);
+  if (values.help) { console.log(HELP); return; }
+
+  const projectRoot = process.cwd();
+  const manifest = km.read(projectRoot);
+  if (!manifest) {
+    console.error(`no ${km.FILE} here. run \`skills-atlas kit\` first.`);
+    process.exitCode = 1; return;
+  }
+  const targetRoot = fsu.installTargetDir({ global: Boolean(values.global) });
+
+  const currentHash = name => {
+    const dest = path.join(targetRoot, name);
+    if (!fsu.dirExists(dest)) return null;
+    try { return fsu.hashDir(dest); } catch { return null; }
+  };
+  const actions = km.planSync(manifest, currentHash);
+
+  if (values['dry-run']) {
+    for (const a of actions) console.log(`  ${a.action.padEnd(14)} ${a.name}`);
+    console.log(dim('\n(dry run — nothing written)'));
+    return;
+  }
+
+  const { data } = loadData({ quiet: values.json });
+  const idx = buildIndices(data);
+  const results = [];
+
+  for (const a of actions) {
+    const rec = { name: a.name, action: a.action };
+    if (a.action === 'up-to-date' && !values.update) { results.push({ ...rec, status: 'up-to-date' }); continue; }
+    if (a.action === 'local-changes' && !values.force) { results.push({ ...rec, status: 'local-changes' }); continue; }
+
+    const chosen = vendorsFor(idx.skillIndex, a.name).find(c => c.source.name === a.declared.source)
+      || vendorsFor(idx.skillIndex, a.name)[0];
+    const docPath = chosen && skillDocPath(chosen.vendor, a.name);
+    if (!docPath) { results.push({ ...rec, status: 'no-folder' }); continue; }
+
+    const v = chosen.vendor, src = chosen.source;
+    const dest = path.join(targetRoot, a.name);
+    try {
+      const r = await installFolder({
+        author: v.author || src.author, repo: v.repo || src.repo,
+        branch: a.declared.ref || v.default_branch || src.default_branch || 'main',
+        docPath, dest, targetRoot, skillName: a.name,
+        source: src.name, group: chosen.row && chosen.row.group, category: chosen.row && chosen.row._cat,
+      });
+      results.push({ ...rec, status: 'installed', hash: r.hash });
+      if (values.update) { a.declared.hash = r.hash; a.declared.ref = r.branchUsed; a.declared.source = src.name; }
+    } catch (e) {
+      results.push({ ...rec, status: 'failed', error: e.message });
+    }
+  }
+
+  if (values.update) km.write(projectRoot, manifest);
+  if (results.some(r => r.status === 'failed')) process.exitCode = 1; // CI-visible failure
+
+  if (values.json) { console.log(JSON.stringify(results, null, 2)); return; }
+  for (const r of results) {
+    const sym = r.status === 'installed' ? green('✓') : r.status === 'up-to-date' ? dim('=') : r.status === 'local-changes' ? '✋' : '✗';
+    console.log(`  ${sym} ${r.name}  ${dim(r.status + (r.error ? ': ' + r.error : ''))}`);
+  }
+  const n = results.filter(r => r.status === 'installed').length;
+  console.log(`\n${n} installed/updated from ${cyan(km.FILE)}.`);
+  if (results.some(r => r.status === 'local-changes')) console.log(dim('skipped local edits — re-run with --force.'));
+};

package/src/detect.js

@@ -0,0 +1,47 @@
+// Detect a project's archetype(s) from on-disk signals. Best-effort and dependency
+// free; always returns at least ['generic']. Pure w.r.t. its `dir` argument.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const readText = p => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
+const readJson = p => { const t = readText(p); if (!t) return null; try { return JSON.parse(t); } catch { return null; } };
+const listdir = d => { try { return fs.readdirSync(d); } catch { return []; } };
+
+function detect(dir = process.cwd()) {
+  const archetypes = new Set();
+  const signals = [];
+  const add = (a, why) => { archetypes.add(a); signals.push(why); };
+
+  // --- Node / package.json ---
+  const pkg = readJson(path.join(dir, 'package.json'));
+  if (pkg) {
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    const names = Object.keys(deps);
+    const anyDep = res => names.some(d => res.some(re => re.test(d)));
+    if (anyDep([/^react(-dom)?$/, /^vue$/, /^svelte$/, /^next$/, /^nuxt$/, /^vite$/, /^@angular\//, /^solid-js$/]))
+      add('web-frontend', 'package.json: a frontend framework (react/vue/next/…)');
+    if (anyDep([/^express$/, /^fastify$/, /^@nestjs\//, /^koa$/, /^hapi$/]))
+      add('backend-service', 'package.json: a web-server framework');
+    if (pkg.bin) add('cli-library', 'package.json: bin field (CLI)');
+  }
+
+  // --- Python ---
+  const py = `${readText(path.join(dir, 'pyproject.toml')) || ''}\n${readText(path.join(dir, 'requirements.txt')) || ''}`.toLowerCase();
+  const hasNotebook = listdir(dir).some(f => f.endsWith('.ipynb'));
+  if (/pandas|numpy|scikit-learn|tensorflow|torch|jupyter/.test(py) || hasNotebook)
+    add('data-ml', 'python: data/ML libraries or notebooks');
+  if (/fastapi|flask|django/.test(py)) add('backend-service', 'python: a web framework');
+
+  // --- Infra ---
+  const entries = listdir(dir);
+  if (entries.some(f => f.endsWith('.tf')) ||
+      fs.existsSync(path.join(dir, 'Dockerfile')) ||
+      entries.some(f => /^docker-compose\.ya?ml$/.test(f)))
+    add('infra-devops', 'infra: terraform/docker files');
+
+  return { archetypes: archetypes.size ? [...archetypes] : ['generic'], signals };
+}
+
+module.exports = { detect };

package/src/kitmanifest.js

@@ -0,0 +1,36 @@
+// The committable, project-root kit declaration: skills-atlas.kit.json.
+// Distinct from the per-dir install ledger (.skills-atlas.json): this is the
+// *intent* ("the kit for this project is X"), committed and shared; `sync` applies it.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const FILE = 'skills-atlas.kit.json';
+const fileFor = root => path.join(root, FILE);
+
+function read(root) {
+  try { return JSON.parse(fs.readFileSync(fileFor(root), 'utf8')); } catch { return null; }
+}
+
+function write(root, m) {
+  fs.writeFileSync(fileFor(root), JSON.stringify(m, null, 2) + '\n');
+}
+
+// Decide what `sync` should do per declared skill. `currentHash(name)` returns the
+// on-disk content hash, or null/undefined if the skill isn't installed.
+//   not installed            -> 'install'
+//   installed, hash matches   -> 'up-to-date'
+//   installed, hash differs   -> 'local-changes' (don't clobber edits without --force)
+function planSync(manifest, currentHash) {
+  return (manifest.skills || []).map(s => {
+    const cur = currentHash(s.name);
+    let action;
+    if (!cur) action = 'install';
+    else if (!s.hash || cur === s.hash) action = 'up-to-date';
+    else action = 'local-changes';
+    return { name: s.name, action, declared: s };
+  });
+}
+
+module.exports = { FILE, fileFor, read, write, planSync };

package/src/kits.js

@@ -0,0 +1,62 @@
+// Curated project kits: a universal core dev workflow plus per-archetype add-ons.
+// Each skill carries a one-line reason. EVERY name here must exist in the catalog
+// (enforced by test/kits.test.js — it already caught a non-existent 'openapi').
+'use strict';
+
+// [skillName, reason]
+const CORE = [
+  ['brainstorming', 'turn an idea into a spec'],
+  ['writing-plans', 'break the work into a plan'],
+  ['executing-plans', 'run the plan task by task'],
+  ['systematic-debugging', 'root-cause a stubborn bug'],
+  ['test-driven-development', 'write tests first'],
+  ['requesting-code-review', 'get a structured review'],
+];
+
+const ARCHETYPES = {
+  'web-frontend': [
+    ['frontend-design', 'component/layout guidance'],
+    ['web-design-guidelines', 'accessibility + performance'],
+    ['webapp-testing', 'browser/E2E testing'],
+  ],
+  'backend-service': [
+    ['sql-queries', 'natural-language → SQL'],
+    ['mcp-builder', 'build an MCP server'],
+  ],
+  'data-ml': [
+    ['data-analysis', 'analyze datasets'],
+    ['exploratory-data-analysis', 'EDA workflow'],
+  ],
+  'infra-devops': [
+    ['security-best-practices', 'secure coding + threat modeling'],
+    ['using-git-worktrees', 'isolated workspace workflow'],
+  ],
+  'cli-library': [],
+  'generic': [],
+};
+
+const ARCHETYPE_NAMES = Object.keys(ARCHETYPES);
+
+// archetypes[] -> [{ name, reason, group }]  (core first, then add-ons, deduped)
+function kitFor(archetypes) {
+  const out = CORE.map(([name, reason]) => ({ name, reason, group: 'core' }));
+  const seen = new Set(out.map(s => s.name));
+  for (const a of archetypes || []) {
+    for (const [name, reason] of (ARCHETYPES[a] || [])) {
+      if (!seen.has(name)) { seen.add(name); out.push({ name, reason, group: a }); }
+    }
+  }
+  return out;
+}
+
+// Add an `installed` flag (from a set of already-present skill names).
+function buildKitPlan(archetypes, installedNames = new Set()) {
+  const skills = kitFor(archetypes).map(s => ({ ...s, installed: installedNames.has(s.name) }));
+  return { archetypes: [...archetypes], skills };
+}
+
+const allKitSkills = () => [
+  ...new Set([...CORE.map(c => c[0]), ...Object.values(ARCHETYPES).flat().map(s => s[0])]),
+];
+
+module.exports = { CORE, ARCHETYPES, ARCHETYPE_NAMES, kitFor, buildKitPlan, allKitSkills };