skills-atlas-cli 0.1.1 → 0.2.0

package/README.md

@@ -46,29 +46,40 @@ 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.
 
 ## How install works
 
-Every skill records the **exact in-repo path** of its `SKILL.md`. `install` reads
-that, lists the skill's folder via one GitHub API call, then downloads each file
-(preserving subfolders) into `<target>/.claude/skills/<skill>/`.
+The real value is the **catalog**: `search` / `info` / `categories` work fully
+offline and map *which* skill fits — function-organized, bilingual, tagged with
+use-case / when-to-use / personas / ⛓ chains. That's what `npx skills add` and
+GitHub search don't give you.
+
+On top of that, `install` can place a skill straight into `.claude/skills/`:
 
-- Unlike `git clone`, it fetches **only that skill's folder**, not the whole repo.
+- For a repo that exposes a **per-skill folder**, it downloads only that folder
+  (via the repo archive — **no GitHub API rate limit**) into
+  `<target>/.claude/skills/<skill>/`, not the whole repo.
 - Several sources? The best installable one is auto-picked — `--source <id>` to
   choose, `--yes` for non-interactive runs.
-- Whole-repo / marketplace sources (no per-skill folder) → `install` prints the
-  exact command to run instead (e.g. `npx skills add owner/repo`).
-- Set `GITHUB_TOKEN` to raise the GitHub API rate limit (60/h → 5000/h).
+- Other sources (whole-repo / marketplace) print their official command instead
+  (e.g. `npx skills add owner/repo`).
+- `GITHUB_TOKEN` is only needed if you fall back to the API and hit its 60/h limit.
 
 ## Keeping the catalog fresh
 

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.1",
+  "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/args.js

@@ -19,6 +19,7 @@ const ALL = {
   json: { type: 'boolean' },
   en: { type: 'boolean' },
   zh: { type: 'boolean' },
+  all: { type: 'boolean' },
   help: { type: 'boolean', short: 'h' },
 };
 

package/src/commands/info.js

@@ -5,13 +5,14 @@ const { loadData } = require('../data');
 const { buildIndices, suggestSkills } = require('../index-build');
 const { buildInfo, renderInfo } = require('../format');
 
-const HELP = `usage: skills-atlas info <skill> [--json] [--zh]
+const HELP = `usage: skills-atlas info <skill> [--all] [--json] [--zh]
 
 Show a skill's description, use case, when-to-use, personas, source repo(s)
-(stars / license / type), the in-repo SKILL.md path, and the install command.`;
+(stars / license / type), the in-repo SKILL.md path, and the install command.
+Leads with the most relevant group; --all expands same-named skills in others.`;
 
 module.exports = async function info(argv) {
-  const { values, positionals } = parse(argv, ['json']);
+  const { values, positionals } = parse(argv, ['json', 'all']);
   if (values.help) { console.log(HELP); return; }
 
   const name = positionals[0];
@@ -42,5 +43,5 @@ module.exports = async function info(argv) {
     console.log(JSON.stringify(infoObj, null, 2));
     return;
   }
-  console.log(renderInfo(infoObj, { en: !values.zh }));
+  console.log(renderInfo(infoObj, { en: !values.zh, all: values.all }));
 };

package/src/commands/install.js

@@ -4,10 +4,11 @@ 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, renderInfo, bold, dim, cyan, green, stars, safeAlt } = require('../format');
+const { buildInfo, infoForRow, renderInfo, bold, dim, cyan, green, stars, safeAlt } = require('../format');
 
 const HELP = `usage: skills-atlas install <skill> [options]
 
@@ -17,11 +18,13 @@ 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
 
-Downloading uses the GitHub API (60 requests/hour unauthenticated). If you hit a
-rate limit, set GITHUB_TOKEN=<your token> to raise it to 5000/hour.`;
+Downloads the repo archive (no GitHub API rate limit). Only if that fetch fails
+does it fall back to the GitHub API (60/h unauthenticated) — set GITHUB_TOKEN to
+raise that fallback to 5000/h.`;
 
 function resolveGlobal(values) {
   if (values.project) return false;
@@ -29,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];
@@ -79,6 +157,17 @@ module.exports = async function install(argv) {
     chosen = candidates[i];
   }
 
+  // Heads-up when --yes auto-picked among semantically different groups.
+  if (values.yes && candidates.length > 1) {
+    const groups = [...new Set(candidates.map(c => c.row && c.row.group).filter(Boolean))];
+    if (groups.length > 1) {
+      const picked = chosen.row && chosen.row.group;
+      const otherGroups = groups.filter(g => g !== picked).join('; ');
+      const st = stars(chosen.source.stars);
+      console.error(dim(`note: '${name}' exists in ${groups.length} groups; auto-picked ${chosen.source.name}${st ? ' ' + st : ''} (${picked || '?'}). also in: ${otherGroups} — use --source to choose.`));
+    }
+  }
+
   const v = chosen.vendor || {};
   const src = chosen.source;
   const skill = chosen.skill || name; // canonical skill name from the index
@@ -113,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? ---
@@ -138,6 +242,15 @@ module.exports = async function install(argv) {
       process.exitCode = 1;
       return;
     }
+    if (values.json) {
+      console.log(JSON.stringify({
+        skill: name, mode: 'folder', dest,
+        files: listing.files.length,
+        scripts: fsu.scriptFiles(listing.files.map(f => f.rel)).length,
+        branch: listing.branchUsed, dryRun: true,
+      }));
+      return;
+    }
     console.log(`would install ${listing.files.length} file(s) to ${fsu.tildify(dest)} (branch ${listing.branchUsed}):`);
     listing.files.forEach(f => console.log(`  ${f.rel}`));
     if (listing.note) console.log(dim('  ' + listing.note));
@@ -145,44 +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;
+  // --- 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;
-    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;
@@ -190,17 +270,27 @@ module.exports = async function install(argv) {
 
   if (values.json) {
     console.log(JSON.stringify({
-      skill: name, mode: 'folder', source: src.name,
-      dest, files: fileCount, 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(`\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
-  const infoObj = buildInfo(skill, { skillIndex: idx.skillIndex, vendors: data.vendors });
-  console.log(renderInfo(infoObj, { en: !values.zh }));
+  // usage guidance — scoped by row identity to the exact group you installed from
+  const guide = chosen.row
+    ? infoForRow(skill, chosen.row, data.vendors)
+    : buildInfo(skill, { skillIndex: idx.skillIndex, vendors: data.vendors });
+  console.log(renderInfo(guide, { en: !values.zh, all: true }));
   console.log(dim('\nStart a new Claude Code session to load the skill, then invoke it by name.'));
 };

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

@@ -55,47 +55,70 @@ const PERSONA_EN = {
   '研究': 'Research', '营销': 'Marketing', '设计': 'Design', '运营': 'Ops', '通用': 'General',
 };
 
-// Structured info for a skill (also used as the machine-readable --json shape).
+// Rank a row best-first: top stars, then total stars, then source count — so a
+// star tie (one popular source shared across namesake groups) breaks meaningfully.
+function rowRank(r) {
+  const ss = (r.sources || []).map(s => s.stars || 0);
+  return { max: Math.max(0, ...ss), sum: ss.reduce((a, b) => a + b, 0), n: ss.length };
+}
+
+// The per-group info object for one row.
+function groupOf(r, skillName, vendors) {
+  return {
+    group: r.group,
+    group_en: r.group_en,
+    category: r._cat,
+    category_en: r._catEn,
+    chain: r.chain,
+    description: r.description,
+    description_en: r.description_en,
+    use_case: r.use_case,
+    use_case_en: r.use_case_en,
+    when_to_use: r.when_to_use,
+    when_to_use_en: r.when_to_use_en,
+    personas: r.personas || [],
+    sources: (r.sources || []).map(s => {
+      const v = vendors[s.name] || {};
+      const docPath = skillDocPath(v, skillName);
+      return {
+        id: s.name,
+        url: s.url,
+        stars: s.stars,
+        license: (v.skill_licenses && v.skill_licenses[skillName]) || s.license || null,
+        type: s.type,
+        path: docPath || null,
+        install: s.install || v.install || null,
+      };
+    }),
+  };
+}
+
+// Structured info for a skill (also the machine-readable --json shape). Groups
+// are ordered best-first so the most relevant one leads.
 function buildInfo(skillName, { skillIndex, vendors }) {
-  const rows = rowsFor(skillIndex, skillName);
+  const rows = rowsFor(skillIndex, skillName).slice().sort((a, b) => {
+    const A = rowRank(a), B = rowRank(b);
+    return B.max - A.max || B.sum - A.sum || B.n - A.n;
+  });
   return {
     skill: skillName,
     found: rows.length > 0,
-    groups: rows.map(r => ({
-      group: r.group,
-      group_en: r.group_en,
-      category: r._cat,
-      category_en: r._catEn,
-      chain: r.chain,
-      description: r.description,
-      description_en: r.description_en,
-      use_case: r.use_case,
-      use_case_en: r.use_case_en,
-      when_to_use: r.when_to_use,
-      when_to_use_en: r.when_to_use_en,
-      personas: r.personas || [],
-      sources: (r.sources || []).map(s => {
-        const v = vendors[s.name] || {};
-        const docPath = skillDocPath(v, skillName);
-        return {
-          id: s.name,
-          url: s.url,
-          stars: s.stars,
-          license: (v.skill_licenses && v.skill_licenses[skillName]) || s.license || null,
-          type: s.type,
-          path: docPath || null,
-          install: s.install || v.install || null,
-        };
-      }),
-    })),
+    groups: rows.map(r => groupOf(r, skillName, vendors)),
   };
 }
 
-function renderInfo(info, { en = false } = {}) {
+// Single-group info for one specific row (scoped post-install guidance — scopes
+// by row identity, so two namesake rows with the same group name don't both show).
+function infoForRow(skillName, row, vendors) {
+  return { skill: skillName, found: true, groups: [groupOf(row, skillName, vendors)] };
+}
+
+function renderInfo(info, { en = false, all = false } = {}) {
   const pick = (zh, e) => (en ? (e || zh) : (zh || e)) || '';
   const out = [];
   out.push(`\n${bold(green(info.skill))}${info.groups.some(g => g.chain) ? ' ' + cyan('⛓') : ''}`);
-  for (const g of info.groups) {
+  const shown = all ? info.groups : info.groups.slice(0, 1);
+  for (const g of shown) {
     out.push(`  ${dim('group:')} ${pick(g.group, g.group_en)}  ${dim('[' + pick(g.category, g.category_en) + ']')}`);
     const desc = pick(g.description, g.description_en);
     if (desc) out.push(`  ${desc}`);
@@ -119,9 +142,15 @@ function renderInfo(info, { en = false } = {}) {
       }
     }
   }
+  if (!all && info.groups.length > 1) {
+    const others = info.groups.slice(1).map(g => pick(g.group, g.group_en));
+    out.push(dim(`  + ${others.length} other group(s) with a same-named skill: ${others.join('; ')}`));
+    out.push(dim(`    (run \`skills-atlas info ${info.skill} --all\` to expand)`));
+  }
   return out.join('\n');
 }
 
 module.exports = {
-  bold, dim, green, cyan, yellow, stars, safeAlt, text, renderRow, buildInfo, renderInfo,
+  bold, dim, green, cyan, yellow, stars, safeAlt, text, renderRow,
+  buildInfo, infoForRow, renderInfo,
 };

package/src/fsutil.js

@@ -46,7 +46,15 @@ function tildify(p) {
   return p.startsWith(home) ? '~' + p.slice(home.length) : p;
 }
 
+// Executable/script files in a skill folder, by extension (for the install
+// transparency heads-up). Conservative: extension-based, won't catch every
+// extensionless executable, so the provenance note is always shown regardless.
+const SCRIPT_RE = /\.(sh|bash|zsh|fish|command|js|cjs|mjs|ts|tsx|jsx|py|rb|pl|ps1|psm1|bat|cmd)$/i;
+function scriptFiles(rels) {
+  return (rels || []).filter(r => SCRIPT_RE.test(r));
+}
+
 module.exports = {
   installTargetDir, dirExists, ensureDir, mkdtemp,
-  writeFileMkdir, rmrf, swapDir, tildify,
+  writeFileMkdir, rmrf, swapDir, tildify, scriptFiles,
 };

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

@@ -88,12 +88,27 @@ function levenshtein(a, b) {
 
 // Nearest skill names for a not-found query.
 function suggestSkills(skillIndex, query, max = 5) {
-  const q = String(query).toLowerCase();
+  const q = String(query).toLowerCase().trim();
+  if (!q) return [];
   const names = [...skillIndex.keys()];
+
+  // 1) substring either way — high-signal.
   const sub = names.filter(n => n.includes(q) || q.includes(n));
   if (sub.length) return sub.slice(0, max);
+
+  // 2) share a meaningful word with the query (helps multi-word misses).
+  const qtokens = q.split(/[^a-z0-9一-鿿]+/)
+    .filter(t => (/[一-鿿]/.test(t) ? t.length >= 2 : t.length >= 3));
+  if (qtokens.length) {
+    const overlap = names.filter(n => qtokens.some(t => n.includes(t)));
+    if (overlap.length) return overlap.slice(0, max);
+  }
+
+  // 3) fuzzy, but GATED to close edits only — return nothing rather than noise.
+  const limit = Math.max(1, Math.floor(q.length * 0.34));
   return names
     .map(n => [n, levenshtein(q, n)])
+    .filter(([, d]) => d <= limit)
     .sort((a, b) => a[1] - b[1])
     .slice(0, max)
     .map(s => s[0]);

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