skills-atlas-cli 0.4.2 → 0.6.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.
 
@@ -93,6 +125,23 @@ On top of that, `install` can place a skill straight into `.claude/skills/`:
 The catalog ships inside the package and works offline. `skills-atlas update` pulls
 the latest from the public feed (cached under `~/.cache/skills-atlas/`).
 
+## Private / org catalog sources
+
+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:
+
+```bash
+skills-atlas registry add https://skills.acme.internal/data.json   # or a local path
+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.
+
 ## In Claude Code
 
 A thin [Claude Code plugin](./plugin) lets Claude do all of this in-conversation —

package/bin/skills.js

@@ -9,6 +9,9 @@ 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 registry = require('../src/commands/registry');
 const suggest = require('../src/commands/suggest');
 const hook = require('../src/commands/hook');
 const update = require('../src/commands/update');
@@ -17,7 +20,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, registry };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -35,6 +38,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
@@ -43,6 +48,7 @@ catalog:
   update             refresh the catalog from the public data feed
   categories         list the top-level categories
   list [category]    list skill groups (optionally within one category)
+  registry           add/list/remove a private catalog source (org-internal skills)
 
 global flags: --zh (中文 output; English by default), --json (machine output), -h/--help
 docs: https://zita-go.github.io/Skills-Atlas/`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.4.2",
+  "version": "0.6.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,9 @@ const ALL = {
   zh: { type: 'boolean' },
   all: { type: 'boolean' },
   inline: { type: 'boolean' },
+  archetype: { type: 'string' },
+  update: { type: 'boolean' },
+  name: { type: 'string' },
   help: { type: 'boolean', short: 'h' },
 };
 

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

@@ -0,0 +1,66 @@
+// `skills-atlas registry add|list|remove` — manage private catalog sources.
+'use strict';
+
+const { parse } = require('../args');
+const { fetchSource, counts, PUBLIC_URL } = require('../data');
+const registry = require('../registry');
+const { green, dim, cyan, bold } = require('../format');
+
+const HELP = `usage: skills-atlas registry <add|list|remove> [url|path]
+
+Manage private catalog sources (a data.json in the same schema). Their skills
+merge into search / info / install / kit; a private source wins a name clash.
+
+  add <url|path>     add a source (--name <label>); fetches + caches it now
+  list               show the public default + your private sources
+  remove <url|path>  drop a source
+
+A source can be an https URL or a local file path. For a private URL behind auth,
+set SKILLS_ATLAS_TOKEN (sent as a Bearer header). CI: SKILLS_ATLAS_SOURCES=url1,url2`;
+
+module.exports = async function registryCmd(argv) {
+  const { values, positionals } = parse(argv, ['json', 'name']);
+  if (values.help) { console.log(HELP); return; }
+  const sub = positionals[0] || 'list';
+  const url = positionals[1];
+
+  if (sub === 'list') {
+    const srcs = registry.effectiveSources();
+    if (values.json) { console.log(JSON.stringify(srcs, null, 2)); return; }
+    console.log(`${bold('public')}  ${PUBLIC_URL}  ${dim('(default)')}`);
+    if (!srcs.length) { console.log(dim('no private sources. add one: skills-atlas registry add <url|path>')); return; }
+    for (const s of srcs) {
+      const cached = registry.readCachedSource(s.url);
+      const n = cached ? Object.keys(cached.vendors || {}).length : 0;
+      console.log(`${green('•')} ${s.name ? bold(s.name) + '  ' : ''}${s.url}  ${dim(cached ? n + ' vendors' : 'not fetched — run skills-atlas update')}`);
+    }
+    return;
+  }
+
+  if (sub === 'add') {
+    if (!url) { console.error('usage: skills-atlas registry add <url|path>'); process.exitCode = 1; return; }
+    try {
+      const d = await fetchSource(url);
+      registry.cacheSource(url, d);
+      registry.addSource(url, { name: values.name });
+      const c = counts(d);
+      if (values.json) { console.log(JSON.stringify({ added: url, counts: c })); return; }
+      console.log(`${green('✓')} added private source ${cyan(url)}  ${dim(`(${c.vendors} vendors, ${c.groups} groups)`)}`);
+      console.log(dim('its skills now appear in search / info / install / kit.'));
+    } catch (e) { console.error(`failed to add ${url}: ${e.message}`); process.exitCode = 1; }
+    return;
+  }
+
+  if (sub === 'remove') {
+    if (!url) { console.error('usage: skills-atlas registry remove <url|path>'); process.exitCode = 1; return; }
+    const removed = registry.removeSource(url);
+    registry.removeCachedSource(url);
+    if (values.json) { console.log(JSON.stringify({ removed: removed ? url : null })); if (!removed) process.exitCode = 1; return; }
+    if (removed) console.log(`${green('✓')} removed ${url}`);
+    else { console.error(`not a configured source: ${url}`); process.exitCode = 1; }
+    return;
+  }
+
+  console.error(`unknown registry subcommand '${sub}'. use: add | list | remove`);
+  process.exitCode = 1;
+};

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/commands/update.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { parse } = require('../args');
-const { refreshData } = require('../data');
+const { refreshData, refreshSources } = require('../data');
 
 module.exports = async function update(argv) {
   const { values } = parse(argv, ['json']);
@@ -12,14 +12,20 @@ module.exports = async function update(argv) {
 
   try {
     const res = await refreshData();
-    if (values.json) { console.log(JSON.stringify(res, null, 2)); return; }
+    const sources = await refreshSources();
+    if (values.json) { console.log(JSON.stringify({ ...res, sources }, null, 2)); return; }
     if (!res.changed) {
       console.log(`catalog already up to date (${res.counts.vendors} vendors, ${res.counts.groups} groups).`);
-      return;
+    } else {
+      const p = res.prevCounts;
+      const was = p ? `  ${'(was ' + p.vendors + ' vendors / ' + p.groups + ' groups)'}` : '';
+      console.log(`updated: ${res.counts.sections} sections, ${res.counts.groups} groups, ${res.counts.vendors} vendors.${was}`);
+    }
+    if (sources.length) {
+      const ok = sources.filter(s => s.ok).length;
+      const failed = sources.filter(s => !s.ok).map(s => s.url);
+      console.log(`private sources: ${ok}/${sources.length} refreshed${failed.length ? ' (failed: ' + failed.join(', ') + ')' : ''}.`);
     }
-    const p = res.prevCounts;
-    const was = p ? `  ${'(was ' + p.vendors + ' vendors / ' + p.groups + ' groups)'}` : '';
-    console.log(`updated: ${res.counts.sections} sections, ${res.counts.groups} groups, ${res.counts.vendors} vendors.${was}`);
   } catch (e) {
     console.error(`update failed: ${e.message}`);
     process.exitCode = 1;

package/src/data.js

@@ -9,6 +9,9 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+const registry = require('./registry');
+const { mergeCatalogs } = require('./merge');
+
 const PUBLIC_URL = 'https://zita-go.github.io/Skills-Atlas/data.json';
 const UA = 'skills-atlas-cli';
 const STALE_DAYS = 30;
@@ -75,13 +78,15 @@ function maybeStaleNudge(fromCache) {
 
 function loadData({ quiet = false } = {}) {
   const cached = tryReadJSON(cacheFile());
-  if (isValid(cached)) {
-    if (!quiet) maybeStaleNudge(true);
-    return { data: cached, source: 'cache', fromCache: true };
-  }
-  const b = loadBundled();
-  if (!quiet) maybeStaleNudge(false);
-  return { ...b, fromCache: false };
+  let base, info;
+  if (isValid(cached)) { base = cached; info = { source: 'cache', fromCache: true }; if (!quiet) maybeStaleNudge(true); }
+  else { const b = loadBundled(); base = b.data; info = { source: b.source, fromCache: false }; if (!quiet) maybeStaleNudge(false); }
+
+  const overlays = registry.effectiveSources()
+    .map(s => registry.readCachedSource(s.url))
+    .filter(isValid);
+  if (!overlays.length) return { data: base, ...info };
+  return { data: mergeCatalogs(base, overlays), source: `${info.source}+${overlays.length}private`, fromCache: info.fromCache };
 }
 
 function ensureDir(d) {
@@ -147,4 +152,40 @@ async function refreshData() {
   };
 }
 
-module.exports = { loadData, refreshData, counts, cacheDir, PUBLIC_URL };
+// Fetch (or read, for a local path / file:// URL) a private catalog source and
+// validate it. Honors SKILLS_ATLAS_TOKEN (Bearer) and SKILLS_ATLAS_TIMEOUT_MS.
+async function fetchSource(src) {
+  if (!/^https?:\/\//i.test(src)) {                  // local file path or file:// URL
+    const p = src.replace(/^file:\/\//, '');
+    let d;
+    try { d = JSON.parse(fs.readFileSync(p, 'utf8')); } catch (e) { throw new Error(`${src}: ${e.message}`); }
+    if (!isValid(d)) throw new Error(`${src}: not a valid catalog (sections/vendors)`);
+    return d;
+  }
+  const headers = { 'User-Agent': UA, Accept: 'application/json' };
+  if (process.env.SKILLS_ATLAS_TOKEN) headers.Authorization = `Bearer ${process.env.SKILLS_ATLAS_TOKEN}`;
+  const ac = new AbortController();
+  const timeoutMs = Number(process.env.SKILLS_ATLAS_TIMEOUT_MS) || 25000;
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  let res;
+  try { res = await fetch(src, { headers, signal: ac.signal }); }
+  catch (e) { throw new Error(e.name === 'AbortError' ? `timed out fetching ${src}` : `network error fetching ${src}: ${e.message}`); }
+  finally { clearTimeout(timer); }
+  if (!res.ok) throw new Error(`fetch failed: HTTP ${res.status} ${res.statusText} (${src})`);
+  let d;
+  try { d = JSON.parse(await res.text()); } catch { throw new Error(`${src}: not valid JSON`); }
+  if (!isValid(d)) throw new Error(`${src}: not a valid catalog (sections/vendors)`);
+  return d;
+}
+
+// Refresh every configured private source into its local cache (best-effort).
+async function refreshSources() {
+  const out = [];
+  for (const s of registry.effectiveSources()) {
+    try { const d = await fetchSource(s.url); registry.cacheSource(s.url, d); out.push({ url: s.url, ok: true, counts: counts(d) }); }
+    catch (e) { out.push({ url: s.url, ok: false, error: e.message }); }
+  }
+  return out;
+}
+
+module.exports = { loadData, refreshData, fetchSource, refreshSources, counts, cacheDir, PUBLIC_URL };

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/index-build.js

@@ -53,6 +53,9 @@ function vendorsFor(skillIndex, skillName) {
     if (id && !seen.has(id)) seen.set(id, e);
   }
   return [...seen.values()].sort((a, b) => {
+    const pa = a.vendor && a.vendor._private ? 1 : 0;
+    const pb = b.vendor && b.vendor._private ? 1 : 0;
+    if (pa !== pb) return pb - pa;               // private sources first (registry override)
     const da = skillDocPath(a.vendor, a.skill) ? 1 : 0;
     const db = skillDocPath(b.vendor, b.skill) ? 1 : 0;
     if (da !== db) return db - da;

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

package/src/merge.js

@@ -0,0 +1,17 @@
+// Merge a base catalog with private overlays. Private vendors are tagged `_private`
+// so `vendorsFor` ranks them first on a same-name clash. Pure — returns a new object,
+// never mutates inputs, and the result lives only in memory (never cached).
+'use strict';
+
+function mergeCatalogs(base, overlays = []) {
+  const vendors = { ...(base.vendors || {}) };
+  const sections = [...(base.sections || [])];
+  for (const ov of overlays) {
+    if (!ov) continue;
+    for (const [id, v] of Object.entries(ov.vendors || {})) vendors[id] = { ...v, _private: true };
+    for (const s of (ov.sections || [])) sections.push(s);
+  }
+  return { sections, vendors };
+}
+
+module.exports = { mergeCatalogs };

package/src/registry.js

@@ -0,0 +1,78 @@
+// Private catalog sources ("registry"): user config + per-source local cache, so
+// an org can point the CLI at its own data.json alongside the public Atlas.
+// Self-contained (own XDG path helpers) to avoid a require cycle with data.js.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+function configDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'skills-atlas');
+}
+const configFile = () => path.join(configDir(), 'config.json');
+
+function cacheDir() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'skills-atlas');
+}
+const sourcesDir = () => path.join(cacheDir(), 'sources');
+
+function readConfig() {
+  try {
+    const c = JSON.parse(fs.readFileSync(configFile(), 'utf8'));
+    if (!Array.isArray(c.sources)) c.sources = [];
+    return c;
+  } catch { return { version: 1, sources: [] }; }
+}
+function writeConfig(c) {
+  fs.mkdirSync(configDir(), { recursive: true });
+  fs.writeFileSync(configFile(), JSON.stringify(c, null, 2) + '\n');
+}
+function addSource(url, opts = {}) {
+  const c = readConfig();
+  const existing = c.sources.find(s => s.url === url);
+  if (existing) { if (opts.name) existing.name = opts.name; }
+  else c.sources.push({ url, name: opts.name || null, addedAt: new Date().toISOString() });
+  writeConfig(c);
+}
+function removeSource(url) {
+  const c = readConfig();
+  const before = c.sources.length;
+  c.sources = c.sources.filter(s => s.url !== url);
+  writeConfig(c);
+  return c.sources.length < before;
+}
+const listSources = () => readConfig().sources;
+
+const envSources = () => (process.env.SKILLS_ATLAS_SOURCES || '')
+  .split(',').map(s => s.trim()).filter(Boolean);
+
+function effectiveSources() {
+  const out = [], seen = new Set();
+  for (const s of listSources()) if (s.url && !seen.has(s.url)) { seen.add(s.url); out.push({ url: s.url, name: s.name || null }); }
+  for (const u of envSources()) if (!seen.has(u)) { seen.add(u); out.push({ url: u, name: null }); }
+  return out;
+}
+
+function sourceCachePath(url) {
+  const h = crypto.createHash('sha1').update(url).digest('hex').slice(0, 16);
+  return path.join(sourcesDir(), `${h}.json`);
+}
+function cacheSource(url, dataObj) {
+  fs.mkdirSync(sourcesDir(), { recursive: true });
+  fs.writeFileSync(sourceCachePath(url), JSON.stringify(dataObj));
+}
+function readCachedSource(url) {
+  try { return JSON.parse(fs.readFileSync(sourceCachePath(url), 'utf8')); } catch { return null; }
+}
+function removeCachedSource(url) {
+  try { fs.rmSync(sourceCachePath(url), { force: true }); } catch { /* ignore */ }
+}
+
+module.exports = {
+  configDir, configFile, readConfig, writeConfig, addSource, removeSource, listSources,
+  effectiveSources, sourceCachePath, cacheSource, readCachedSource, removeCachedSource,
+};