skills-atlas-cli 0.1.2 → 0.3.0

package/README.md

@@ -46,14 +46,26 @@ skills-atlas info brainstorming
 # 📥 Install it (into .claude/skills/)
 skills-atlas install brainstorming             # → ~/.claude/skills/   (default, all projects)
 skills-atlas install brainstorming --project   # → ./.claude/skills/   (this project only)
+skills-atlas install brainstorming --chain     # install the whole ⛓ workflow it belongs to
 skills-atlas install brainstorming --dry-run   # preview the files, write nothing
 
-# 🗂️ Browse & refresh
+# 🗂️ Manage what you've installed   (like a package manager)
+skills-atlas installed                         # list installed (global + project)
+skills-atlas outdated                          # which have a newer upstream version
+skills-atlas upgrade brainstorming             # re-fetch to latest (--all; won't clobber local edits)
+skills-atlas remove brainstorming              # delete it
+skills-atlas doctor                            # health check: orphans, drift, license/script risks
+
+# 🌐 Catalog
 skills-atlas categories                        # the 20 top-level categories
 skills-atlas list marketing                    # skill groups within a category
 skills-atlas update                            # pull the latest catalog
 ```
 
+**⛓ Workflows, not just skills.** Many skills belong to a curated chain (e.g.
+`brainstorming → writing-plans → executing-plans → …`). `install <skill> --chain`
+installs the whole pipeline in one archive download, ready to run in order.
+
 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.
 

package/bin/skills.js

@@ -4,20 +4,34 @@
 const search = require('../src/commands/search');
 const info = require('../src/commands/info');
 const install = require('../src/commands/install');
+const installed = require('../src/commands/installed');
+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 update = require('../src/commands/update');
 const { categories, list } = require('../src/commands/categories');
 
 const VERSION = require('../package.json').version;
-const commands = { search, info, install, update, categories, list };
+const commands = { search, info, install, installed, upgrade, remove, outdated, doctor, update, categories, list };
 
-const HELP = `skills-atlas — search, install & learn AI agent skills
+const HELP = `skills-atlas — search, install & manage AI agent skills
 
 usage: skills-atlas <command> [args]
 
-commands:
+find & install:
   search <query>     find skills (filters: -c category, -p persona, -t type, --chain)
   info <skill>       show description, usage guidance, sources & install command
-  install <skill>    download the skill into .claude/skills/ (--global default, --project)
+  install <skill>    download into .claude/skills/ (--chain for the whole workflow)
+
+manage what you've installed:
+  installed          list installed skills (global + project)
+  outdated           show which installed skills have a newer upstream version
+  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
+
+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)

package/package.json

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

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, rowsFor } = require('../index-build');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { dim, yellow, green } = require('../format');
+
+const RISKY_LICENSE = /\bNC\b|GPL|AGPL|Commons[- ]?Clause/i;
+
+module.exports = async function doctor(argv) {
+  const { values } = parse(argv, ['global', 'project', 'json']);
+  if (values.help) { console.log('usage: skills-atlas doctor [--global|--project] [--json]'); return; }
+
+  const { data } = loadData({ quiet: values.json });
+  const idx = buildIndices(data);
+  const findings = [];
+  const seen = {}; // skill -> [scopes]
+
+  for (const s of fsu.scopesFor(values)) {
+    const root = s.root;
+    const m = manifest.read(root);
+
+    let folders = [];
+    try {
+      folders = fs.readdirSync(root, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
+    } catch { /* no skills dir yet */ }
+
+    for (const [skill, e] of Object.entries(m.skills)) {
+      seen[skill] = (seen[skill] || []).concat(s.name);
+      const dir = path.join(root, skill);
+      if (!fsu.dirExists(dir)) { findings.push({ scope: s.name, skill, level: 'warn', msg: 'recorded but folder missing on disk' }); continue; }
+      if (!fs.existsSync(path.join(dir, 'SKILL.md'))) findings.push({ scope: s.name, skill, level: 'error', msg: 'no SKILL.md in folder' });
+      if (!data.vendors[e.source] || !rowsFor(idx.skillIndex, skill).length) findings.push({ scope: s.name, skill, level: 'info', msg: 'no longer in the catalog' });
+      if (e.scripts) findings.push({ scope: s.name, skill, level: 'info', msg: `ships ${e.scripts} script file(s) — review` });
+      const vendor = data.vendors[e.source];
+      if (vendor && vendor.license && RISKY_LICENSE.test(vendor.license)) findings.push({ scope: s.name, skill, level: 'warn', msg: `license: ${vendor.license}` });
+    }
+
+    for (const f of folders) {
+      if (!m.skills[f]) findings.push({ scope: s.name, skill: f, level: 'info', msg: 'folder not tracked by skills-atlas' });
+    }
+  }
+
+  for (const [skill, scopes] of Object.entries(seen)) {
+    if (scopes.length > 1) findings.push({ scope: scopes.join('+'), skill, level: 'warn', msg: 'installed in both scopes (project shadows global)' });
+  }
+
+  if (values.json) { console.log(JSON.stringify(findings, null, 2)); return; }
+  if (!findings.length) { console.log(`${green('✓')} all good — no issues found.`); return; }
+
+  const order = { error: 0, warn: 1, info: 2 };
+  findings.sort((a, b) => order[a.level] - order[b.level]);
+  for (const f of findings) {
+    const tag = f.level === 'error' ? '✗' : f.level === 'warn' ? yellow('!') : dim('·');
+    console.log(`  ${tag} ${f.skill} ${dim(`[${f.scope}]`)}  ${f.msg}`);
+  }
+  const e = findings.filter(f => f.level === 'error').length;
+  const w = findings.filter(f => f.level === 'warn').length;
+  console.log(`\n${e} error(s), ${w} warning(s), ${findings.length - e - w} note(s).`);
+};

package/src/commands/install.js

@@ -4,8 +4,9 @@ const path = require('path');
 const { parse } = require('../args');
 const { loadData } = require('../data');
 const { buildIndices, vendorsFor, suggestSkills, skillDocPath } = require('../index-build');
-const { listSkillFiles, fetchRaw, fetchSkillFolderTar } = require('../github');
+const { listSkillFiles } = require('../github');
 const fsu = require('../fsutil');
+const { installFolder } = require('../installer');
 const { confirm, choose } = require('../prompt');
 const { buildInfo, infoForRow, renderInfo, bold, dim, cyan, green, stars, safeAlt } = require('../format');
 
@@ -17,6 +18,7 @@ options:
   -s, --source <id>  pick a source when a skill has several
   -f, --force        overwrite if already installed
   -y, --yes          non-interactive (auto-pick top source, assume yes)
+      --chain        install the whole ⛓ workflow this skill belongs to
       --dry-run      show what would download, write nothing
       --json         machine-readable output
 
@@ -30,9 +32,56 @@ function resolveGlobal(values) {
   return true; // default: global
 }
 
+// Install every installable skill in a chain (workflow). One archive download
+// serves them all (github archive cache).
+async function installChain({ row, vendor, src, targetRoot, values }) {
+  const author = vendor.author || src.author;
+  const repo = vendor.repo || src.repo;
+  const branch = vendor.default_branch || src.default_branch || 'main';
+
+  const items = [], skipped = [];
+  for (const sk of row.skills || []) {
+    const dp = skillDocPath(vendor, sk);
+    if (dp) items.push({ name: sk, docPath: dp }); else skipped.push(sk);
+  }
+  if (!items.length) {
+    console.error(`no installable skills in this chain from ${src.name}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!values.json) console.log(`\ninstalling ${items.length}-skill chain from ${bold(src.name)}: ${dim(items.map(i => i.name).join(' → '))}`);
+  const installed = [], failed = [];
+  for (const it of items) {
+    const dest = path.join(targetRoot, it.name);
+    if (fsu.dirExists(dest) && !values.force) {
+      if (!values.json) console.log(dim(`  • ${it.name} — already installed (use --force to overwrite)`));
+      installed.push(it.name);
+      continue;
+    }
+    try {
+      const r = await installFolder({ author, repo, branch, docPath: it.docPath, dest, targetRoot, skillName: it.name, source: src.name, group: row && row.group, category: row && row._cat });
+      if (!values.json) console.log(`  ${green('✓')} ${it.name}  ${dim(`(${r.fileCount} files)`)}`);
+      installed.push(it.name);
+    } catch (e) {
+      if (!values.json) console.log(dim(`  ✗ ${it.name} — ${e.message}`));
+      failed.push(it.name);
+    }
+  }
+
+  if (values.json) {
+    console.log(JSON.stringify({ mode: 'chain', group: row.group, dest: targetRoot, installed, failed, skipped }));
+    return;
+  }
+  if (skipped.length) console.log(dim(`  (skipped ${skipped.length}: ${skipped.join(', ')} — no per-skill folder)`));
+  console.log(`\n${green('✓')} chain ready — ${installed.length} skill(s) in ${fsu.tildify(targetRoot)}`);
+  console.log(dim(`  run in order: ${(row.skills || []).join(' → ')}`));
+  console.log(dim('\nStart a new Claude Code session to load them, then run the workflow in order.'));
+}
+
 module.exports = async function install(argv) {
   const { values, positionals } = parse(argv,
-    ['global', 'project', 'source', 'force', 'yes', 'dry-run', 'json']);
+    ['global', 'project', 'source', 'force', 'yes', 'chain', 'dry-run', 'json']);
   if (values.help) { console.log(HELP); return; }
 
   const name = positionals[0];
@@ -125,6 +174,21 @@ module.exports = async function install(argv) {
   }
 
   const targetRoot = fsu.installTargetDir({ global: resolveGlobal(values) });
+  const isChain = Boolean(chosen.row && chosen.row.chain && (chosen.row.skills || []).length >= 2);
+
+  // --- chain: install the whole workflow ---
+  if (values.chain) {
+    if (!isChain) {
+      console.log(dim(`'${skill}' isn't part of a multi-skill chain; installing it alone.`));
+    } else if (values['dry-run']) {
+      console.log(`would install the ${chosen.row.skills.length}-skill chain: ${chosen.row.skills.join(' → ')}`);
+      return;
+    } else {
+      await installChain({ row: chosen.row, vendor: v, src, targetRoot, values });
+      return;
+    }
+  }
+
   const dest = path.join(targetRoot, skill); // folder = skill name (strips repo nesting)
 
   // --- already installed? ---
@@ -166,45 +230,11 @@ module.exports = async function install(argv) {
     return;
   }
 
-  // --- download into a tmp dir, then atomically swap into place ---
-  // Primary: one repo-archive download from codeload (not GitHub-API rate-limited);
-  // extract only this skill's folder. Fallback: tree API + raw per file.
-  const tmp = fsu.mkdtemp();
-  let branchUsed, fileCount, note = null, scripts = [];
+  // --- single skill: download (archive → API fallback), record, report ---
+  let result;
   try {
-    let folder = null;
-    try {
-      folder = await fetchSkillFolderTar({ author, repo, branch, docPath });
-    } catch (e) {
-      note = `archive download failed (${e.message}); fell back to the GitHub API`;
-    }
-
-    let rels;
-    if (folder && folder.files.length) {
-      branchUsed = folder.branchUsed;
-      for (const f of folder.files) fsu.writeFileMkdir(path.join(tmp, f.rel), f.data);
-      rels = folder.files.map(f => f.rel);
-    } else {
-      const listing = await listSkillFiles({ author, repo, branch, docPath });
-      branchUsed = listing.branchUsed;
-      if (listing.note) note = listing.note;
-      for (const f of listing.files) {
-        const buf = await fetchRaw(author, repo, listing.branchUsed, f.path);
-        fsu.writeFileMkdir(path.join(tmp, f.rel), buf);
-      }
-      rels = listing.files.map(f => f.rel);
-    }
-
-    const hasSkillMd = rels.some(rel => {
-      const r = rel.toLowerCase();
-      return r === 'skill.md' || r.endsWith('/skill.md');
-    });
-    if (!hasSkillMd) throw new Error('no SKILL.md found in downloaded folder');
-    fileCount = rels.length;
-    scripts = fsu.scriptFiles(rels);
-    fsu.swapDir(tmp, dest);
+    result = await installFolder({ author, repo, branch, docPath, dest, targetRoot, skillName: skill, source: src.name, group: chosen.row && chosen.row.group, category: chosen.row && chosen.row._cat });
   } catch (e) {
-    fsu.rmrf(tmp);
     console.error(`install failed: ${e.message}`);
     process.exitCode = 1;
     return;
@@ -212,18 +242,21 @@ module.exports = async function install(argv) {
 
   if (values.json) {
     console.log(JSON.stringify({
-      skill: name, mode: 'folder', source: src.name,
-      dest, files: fileCount, scripts: scripts.length, branch: branchUsed,
+      skill, mode: 'folder', source: src.name,
+      dest: result.dest, files: result.fileCount, scripts: result.scripts.length, branch: result.branchUsed,
     }));
     return;
   }
 
-  console.log(`\n${green('✓')} installed ${bold(skill)} → ${fsu.tildify(dest)}  ${dim(`(${fileCount} file(s) from ${src.name}@${branchUsed})`)}`);
-  if (note) console.log(dim('  ' + note));
-  console.log(dim(`  source: ${src.name}@${branchUsed} — branch HEAD, not a pinned commit; review before use`));
-  if (scripts.length) {
-    const show = scripts.slice(0, 6).join(', ') + (scripts.length > 6 ? ', …' : '');
-    console.log(dim(`  ⚠ includes ${scripts.length} script file(s): ${show}`));
+  console.log(`\n${green('✓')} installed ${bold(skill)} → ${fsu.tildify(result.dest)}  ${dim(`(${result.fileCount} file(s) from ${src.name}@${result.branchUsed})`)}`);
+  if (result.note) console.log(dim('  ' + result.note));
+  console.log(dim(`  source: ${src.name}@${result.branchUsed} — branch HEAD, not a pinned commit; review before use`));
+  if (result.scripts.length) {
+    const show = result.scripts.slice(0, 6).join(', ') + (result.scripts.length > 6 ? ', …' : '');
+    console.log(dim(`  ⚠ includes ${result.scripts.length} script file(s): ${show}`));
+  }
+  if (isChain) {
+    console.log(dim(`  ⛓ part of a ${chosen.row.skills.length}-skill workflow — install all: skills-atlas install ${skill} --chain`));
   }
 
   // usage guidance — scoped by row identity to the exact group you installed from

package/src/commands/installed.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const { parse } = require('../args');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { bold, dim, cyan } = require('../format');
+
+const HELP = `usage: skills-atlas installed [--global|--project] [--json]
+
+List skills installed by skills-atlas (from the per-target manifest).
+Default: both global (~/.claude/skills) and project (./.claude/skills).`;
+
+module.exports = async function installed(argv) {
+  const { values } = parse(argv, ['global', 'project', 'json']);
+  if (values.help) { console.log(HELP); return; }
+
+  const scopes = [];
+  if (values.project && !values.global) {
+    scopes.push({ name: 'project', root: fsu.installTargetDir({ global: false }) });
+  } else if (values.global && !values.project) {
+    scopes.push({ name: 'global', root: fsu.installTargetDir({ global: true }) });
+  } else {
+    scopes.push({ name: 'global', root: fsu.installTargetDir({ global: true }) });
+    scopes.push({ name: 'project', root: fsu.installTargetDir({ global: false }) });
+  }
+
+  const out = scopes.map(s => ({ scope: s.name, root: s.root, skills: manifest.list(s.root) }));
+
+  if (values.json) { console.log(JSON.stringify(out, null, 2)); return; }
+
+  let total = 0;
+  for (const s of out) {
+    if (!s.skills.length) continue;
+    console.log(`\n${bold(s.scope)}  ${dim(fsu.tildify(s.root))}`);
+    for (const e of s.skills.slice().sort((a, b) => a.skill.localeCompare(b.skill))) {
+      total++;
+      const when = e.installedAt ? e.installedAt.slice(0, 10) : '';
+      const meta = [`${e.source || '?'}@${e.branch || '?'}`, e.group, when].filter(Boolean).join(' · ');
+      console.log(`  ${cyan(e.skill)}  ${dim(meta)}`);
+    }
+  }
+  if (!total) {
+    console.log('no skills installed by skills-atlas yet.');
+    console.log(dim('find one: skills-atlas search <query>  →  skills-atlas install <skill>'));
+  }
+};

package/src/commands/outdated.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { cyan, dim, yellow } = require('../format');
+
+const day = s => (s ? String(s).slice(0, 10) : null);
+
+module.exports = async function outdated(argv) {
+  const { values } = parse(argv, ['global', 'project', 'json']);
+  if (values.help) { console.log('usage: skills-atlas outdated [--global|--project] [--json]'); return; }
+
+  const { data } = loadData({ quiet: values.json });
+  const report = [];
+  for (const s of fsu.scopesFor(values)) {
+    for (const e of manifest.list(s.root)) {
+      const vendor = data.vendors[e.source];
+      let status, latest = null;
+      if (!vendor) {
+        status = 'not-in-catalog';
+      } else {
+        latest = vendor.last_commit || null;
+        const inst = day(e.installedAt);
+        status = (latest && inst && day(latest) > inst) ? 'outdated' : 'up-to-date';
+      }
+      report.push({ scope: s.name, skill: e.skill, source: e.source, installed: day(e.installedAt), latest, status });
+    }
+  }
+
+  if (values.json) { console.log(JSON.stringify(report, null, 2)); return; }
+  if (!report.length) { console.log('no skills installed by skills-atlas.'); return; }
+
+  for (const r of report) {
+    const tag = r.status === 'outdated' ? yellow('outdated')
+      : r.status === 'not-in-catalog' ? dim('not in catalog') : dim('up to date');
+    console.log(`  ${cyan(r.skill)} ${dim(`[${r.scope}]`)}  inst ${r.installed || '?'} · ${r.source || '?'}@${r.latest || '?'}  ${tag}`);
+  }
+  const n = report.filter(r => r.status === 'outdated').length;
+  const orphan = report.filter(r => r.status === 'not-in-catalog').length;
+  console.log(`\n${n} outdated${orphan ? `, ${orphan} not in catalog` : ''}.`);
+  if (n) console.log(dim('upgrade: skills-atlas upgrade --all   (or upgrade <skill>)'));
+};

package/src/commands/remove.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('path');
+const { parse } = require('../args');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { confirm } = require('../prompt');
+const { green, dim } = require('../format');
+
+module.exports = async function remove(argv) {
+  const { values, positionals } = parse(argv, ['global', 'project', 'yes', 'json']);
+  if (values.help) { console.log('usage: skills-atlas remove <skill> [--global|--project] [--yes]'); return; }
+
+  const name = positionals[0];
+  if (!name) { console.error('usage: skills-atlas remove <skill>'); process.exitCode = 1; return; }
+
+  const global = !values.project;
+  const root = fsu.installTargetDir({ global });
+  const dest = path.join(root, name);
+  const tracked = manifest.read(root).skills[name];
+
+  if (!fsu.dirExists(dest) && !tracked) {
+    console.error(`'${name}' is not installed (${global ? 'global' : 'project'}).`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!values.yes && !values.json) {
+    const ok = await confirm(`remove ${fsu.tildify(dest)}?`, false);
+    if (!ok) { console.log('aborted.'); return; }
+  }
+
+  if (fsu.dirExists(dest)) fsu.rmrf(dest);
+  manifest.remove(root, name);
+
+  if (values.json) { console.log(JSON.stringify({ removed: name, dest })); return; }
+  console.log(`${green('✓')} removed ${name}  ${dim(fsu.tildify(dest))}`);
+};

package/src/commands/upgrade.js

@@ -0,0 +1,91 @@
+'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 manifest = require('../manifest');
+const { green, dim } = require('../format');
+
+module.exports = async function upgrade(argv) {
+  const { values, positionals } = parse(argv, ['global', 'project', 'all', 'force', 'json']);
+  if (values.help) {
+    console.log('usage: skills-atlas upgrade [<skill> | --all] [--global|--project] [--force]\n\n' +
+      'Re-fetch installed skills to the latest. Refuses to overwrite a folder you\n' +
+      'have edited locally (or one installed before change-tracking) unless --force.');
+    return;
+  }
+  if (!values.all && !positionals[0]) {
+    console.error('usage: skills-atlas upgrade <skill> | --all');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Collect (scope, skill) targets across the selected scopes (default: both),
+  // so `outdated` (both scopes) → `upgrade --all` covers the same skills.
+  const targets = [];
+  for (const s of fsu.scopesFor(values)) {
+    const m = manifest.read(s.root);
+    const names = values.all ? Object.keys(m.skills) : (m.skills[positionals[0]] ? [positionals[0]] : []);
+    for (const n of names) targets.push({ scope: s, name: n, entry: m.skills[n] });
+  }
+  if (!targets.length) {
+    if (values.json) { console.log('[]'); return; }
+    console.log(positionals[0] ? `'${positionals[0]}' is not installed by skills-atlas.` : 'nothing installed to upgrade.');
+    return;
+  }
+
+  const { data } = loadData({ quiet: values.json });
+  const idx = buildIndices(data);
+  const results = [];
+
+  for (const { scope, name, entry } of targets) {
+    const root = scope.root;
+    const rec = { skill: name, scope: scope.name };
+
+    const chosen = vendorsFor(idx.skillIndex, name).find(c => c.source.name === entry.source)
+      || vendorsFor(idx.skillIndex, name)[0];
+    if (!chosen) { results.push({ ...rec, status: 'not-in-catalog' }); continue; }
+
+    const v = chosen.vendor, src = chosen.source;
+    const docPath = skillDocPath(v, name);
+    if (!docPath) { results.push({ ...rec, status: 'no-folder' }); continue; }
+
+    const dest = path.join(root, name);
+    // drift guard — never clobber edits, and never clobber a folder of unknown
+    // provenance (installed before hashes existed) without --force.
+    if (fsu.dirExists(dest) && !values.force) {
+      if (!entry.hash) { results.push({ ...rec, status: 'no-baseline' }); continue; }
+      let cur = null;
+      try { cur = fsu.hashDir(dest); } catch { /* unreadable → fall through */ }
+      if (cur && cur !== entry.hash) { results.push({ ...rec, status: 'local-changes' }); continue; }
+    }
+
+    try {
+      const r = await installFolder({
+        author: v.author || src.author, repo: v.repo || src.repo,
+        branch: v.default_branch || src.default_branch || 'main',
+        docPath, dest, targetRoot: root, skillName: name,
+        source: src.name, group: chosen.row && chosen.row.group, category: chosen.row && chosen.row._cat,
+      });
+      results.push({ ...rec, status: (entry.hash && r.hash === entry.hash) ? 'up-to-date' : 'upgraded', files: r.fileCount });
+    } catch (e) {
+      results.push({ ...rec, status: 'failed', error: e.message });
+    }
+  }
+
+  if (values.json) { console.log(JSON.stringify(results, null, 2)); return; }
+  for (const r of results) {
+    const sym = r.status === 'upgraded' ? green('✓')
+      : r.status === 'up-to-date' ? dim('=')
+        : (r.status === 'local-changes' || r.status === 'no-baseline') ? '✋' : '✗';
+    console.log(`  ${sym} ${r.skill} ${dim(`[${r.scope}]`)}  ${dim(r.status + (r.error ? ': ' + r.error : ''))}`);
+  }
+  const up = results.filter(r => r.status === 'upgraded').length;
+  console.log(`\n${up} upgraded.`);
+  if (results.some(r => r.status === 'local-changes' || r.status === 'no-baseline')) {
+    console.log(dim('skipped some (local edits, or installed before change-tracking) — re-run with --force.'));
+  }
+};

package/src/fsutil.js

@@ -4,6 +4,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 
 // Where skills get installed. Global => ~/.claude/skills, project => ./.claude/skills.
 function installTargetDir({ global }) {
@@ -11,6 +12,15 @@ function installTargetDir({ global }) {
   return path.join(root, '.claude', 'skills');
 }
 
+// Scopes to act on from --global / --project flags (default: both).
+function scopesFor(values) {
+  const g = { name: 'global', root: installTargetDir({ global: true }) };
+  const p = { name: 'project', root: installTargetDir({ global: false }) };
+  if (values.project && !values.global) return [p];
+  if (values.global && !values.project) return [g];
+  return [g, p];
+}
+
 function dirExists(p) {
   try { return fs.statSync(p).isDirectory(); } catch { return false; }
 }
@@ -54,7 +64,31 @@ function scriptFiles(rels) {
   return (rels || []).filter(r => SCRIPT_RE.test(r));
 }
 
+// Stable content hash of a folder, for drift detection on upgrade.
+function hashFiles(files) {
+  const h = crypto.createHash('sha256');
+  for (const f of [...files].sort((a, b) => (a.rel < b.rel ? -1 : 1))) {
+    h.update(f.rel); h.update('\0'); h.update(f.data); h.update('\0');
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+// Same hash, read from an installed directory on disk.
+function hashDir(dir) {
+  const files = [];
+  const walk = (d, base) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const rel = base ? `${base}/${e.name}` : e.name;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p, rel);
+      else files.push({ rel, data: fs.readFileSync(p) });
+    }
+  };
+  walk(dir, '');
+  return hashFiles(files);
+}
+
 module.exports = {
-  installTargetDir, dirExists, ensureDir, mkdtemp,
-  writeFileMkdir, rmrf, swapDir, tildify, scriptFiles,
+  installTargetDir, scopesFor, dirExists, ensureDir, mkdtemp,
+  writeFileMkdir, rmrf, swapDir, tildify, scriptFiles, hashFiles, hashDir,
 };

package/src/github.js

@@ -180,12 +180,19 @@ function extractTarGz(gzBuf, folderPath) {
   return out;
 }
 
+// One archive per repo@ref per process — so installing a whole chain (many
+// skills from one repo) downloads the archive ONCE.
+const _archiveCache = new Map();
 async function fetchArchive(author, repo, ref) {
+  const key = `${author}/${repo}@${ref}`;
+  if (_archiveCache.has(key)) return _archiveCache.get(key);
   const url = `https://codeload.github.com/${author}/${repo}/tar.gz/${ref}`;
   const res = await fetchT(url, { headers: { 'User-Agent': UA } });
   if (res.status === 404) { const e = new Error(`archive not found: ${ref}`); e.code = 'NOT_FOUND'; throw e; }
   if (!res.ok) throw new Error(`codeload HTTP ${res.status}`);
-  return Buffer.from(await res.arrayBuffer());
+  const buf = Buffer.from(await res.arrayBuffer());
+  _archiveCache.set(key, buf);
+  return buf;
 }
 
 // Resolve a skill's folder via the repo archive. Returns { files:[{rel,data}],
@@ -212,4 +219,27 @@ async function fetchSkillFolderTar({ author, repo, branch, docPath }) {
   return { files, branchUsed, source: 'archive' };
 }
 
-module.exports = { listSkillFiles, fetchRaw, fetchTree, fetchSkillFolderTar, extractTarGz };
+// Resolve a skill's folder CONTENTS — archive first (no API budget), tree+raw
+// fallback. Returns { files:[{rel,data}], branchUsed, source, note }.
+async function getSkillFolder({ author, repo, branch, docPath }) {
+  let archiveErr = null;
+  try {
+    const folder = await fetchSkillFolderTar({ author, repo, branch, docPath });
+    if (folder && folder.files.length) {
+      return { files: folder.files, branchUsed: folder.branchUsed, source: 'archive', note: null };
+    }
+  } catch (e) {
+    archiveErr = e.message;
+  }
+  const listing = await listSkillFiles({ author, repo, branch, docPath });
+  const files = [];
+  for (const f of listing.files) {
+    files.push({ rel: f.rel, data: await fetchRaw(author, repo, listing.branchUsed, f.path) });
+  }
+  const note = archiveErr ? `archive unavailable (${archiveErr}); used the GitHub API` : listing.note;
+  return { files, branchUsed: listing.branchUsed, source: 'api', note };
+}
+
+module.exports = {
+  listSkillFiles, fetchRaw, fetchTree, fetchSkillFolderTar, extractTarGz, getSkillFolder,
+};

package/src/installer.js

@@ -0,0 +1,39 @@
+// Shared install primitive used by both `install` (single + chain) and `upgrade`.
+'use strict';
+
+const path = require('path');
+const { getSkillFolder } = require('./github');
+const fsu = require('./fsutil');
+const manifest = require('./manifest');
+
+const hasSkillMd = rels => rels.some(r => {
+  const x = r.toLowerCase();
+  return x === 'skill.md' || x.endsWith('/skill.md');
+});
+
+// Download a skill's folder, atomically install into dest, and record the
+// manifest (with a content hash for drift detection on upgrade).
+// Returns { dest, fileCount, scripts, branchUsed, note, hash }. Throws on failure.
+async function installFolder({ author, repo, branch, docPath, dest, targetRoot, skillName, source, group, category }) {
+  const folder = await getSkillFolder({ author, repo, branch, docPath });
+  const tmp = fsu.mkdtemp();
+  try {
+    for (const f of folder.files) fsu.writeFileMkdir(path.join(tmp, f.rel), f.data);
+    const rels = folder.files.map(f => f.rel);
+    if (!hasSkillMd(rels)) throw new Error('no SKILL.md found in downloaded folder');
+    fsu.swapDir(tmp, dest);
+    const scripts = fsu.scriptFiles(rels);
+    const hash = fsu.hashFiles(folder.files);
+    manifest.record(targetRoot, {
+      skill: skillName, source, repo, branch: folder.branchUsed,
+      group, category, files: rels.length, scripts: scripts.length, hash,
+      installedAt: new Date().toISOString(),
+    });
+    return { dest, fileCount: rels.length, scripts, branchUsed: folder.branchUsed, note: folder.note, hash };
+  } catch (e) {
+    fsu.rmrf(tmp);
+    throw e;
+  }
+}
+
+module.exports = { installFolder, hasSkillMd };

package/src/manifest.js

@@ -0,0 +1,57 @@
+// Per-target install ledger: <skills-root>/.skills-atlas.json. Turns the opaque
+// .claude/skills directory into a managed inventory — the keystone that lets
+// `installed` / future `outdated` / `upgrade` / `remove` / `sync` work.
+// (A dotfile, so Claude Code never loads it as a skill.)
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const FILE = '.skills-atlas.json';
+
+const fileFor = root => path.join(root, FILE);
+
+function read(root) {
+  try {
+    const m = JSON.parse(fs.readFileSync(fileFor(root), 'utf8'));
+    if (!m.skills) m.skills = {};
+    return m;
+  } catch {
+    return { version: 1, skills: {} };
+  }
+}
+
+function write(root, m) {
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(fileFor(root), JSON.stringify(m, null, 2) + '\n');
+}
+
+// Upsert one installed skill.
+function record(root, entry) {
+  const m = read(root);
+  m.skills[entry.skill] = {
+    source: entry.source || null,
+    repo: entry.repo || null,
+    branch: entry.branch || null,
+    group: entry.group || null,
+    category: entry.category || null,
+    files: entry.files ?? null,
+    scripts: entry.scripts ?? 0,
+    hash: entry.hash || null,
+    installedAt: entry.installedAt || null,
+  };
+  write(root, m);
+}
+
+function remove(root, skill) {
+  const m = read(root);
+  if (m.skills[skill]) { delete m.skills[skill]; write(root, m); return true; }
+  return false;
+}
+
+function list(root) {
+  const m = read(root);
+  return Object.entries(m.skills).map(([skill, v]) => ({ skill, ...v }));
+}
+
+module.exports = { read, write, record, remove, list, fileFor, FILE };