skills-atlas-cli 0.1.2 → 0.2.0

package/README.md

@@ -46,14 +46,20 @@ 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 & browse
+skills-atlas installed                         # what you've installed (global + project)
 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,11 +4,12 @@
 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 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, update, categories, list };
 
 const HELP = `skills-atlas — search, install & learn AI agent skills
 
@@ -17,7 +18,8 @@ usage: skills-atlas <command> [args]
 commands:
   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 the skill into .claude/skills/ (--chain for the whole workflow)
+  installed          list skills you've installed (global + project)
   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.2.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/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, getSkillFolder } = require('../github');
 const fsu = require('../fsutil');
+const manifest = require('../manifest');
 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,84 @@ function resolveGlobal(values) {
   return true; // default: global
 }
 
+const hasSkillMd = rels => rels.some(r => {
+  const x = r.toLowerCase();
+  return x === 'skill.md' || x.endsWith('/skill.md');
+});
+
+// Download one skill's folder and atomically install it; records the manifest.
+// Returns { dest, fileCount, scripts, branchUsed, note }. Throws on failure.
+async function installFolder({ author, repo, branch, docPath, dest, targetRoot, skillName, src, row }) {
+  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);
+    manifest.record(targetRoot, {
+      skill: skillName, source: src.name, repo, branch: folder.branchUsed,
+      group: row && row.group, category: row && row._cat,
+      files: rels.length, scripts: scripts.length, installedAt: new Date().toISOString(),
+    });
+    return { dest, fileCount: rels.length, scripts, branchUsed: folder.branchUsed, note: folder.note };
+  } catch (e) {
+    fsu.rmrf(tmp);
+    throw e;
+  }
+}
+
+// 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, src, row });
+      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 +202,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 +258,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, src, row: chosen.row });
   } catch (e) {
-    fsu.rmrf(tmp);
     console.error(`install failed: ${e.message}`);
     process.exitCode = 1;
     return;
@@ -212,18 +270,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/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/manifest.js

@@ -0,0 +1,56 @@
+// 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,
+    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 };