skills-atlas-cli 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "skills-atlas-cli",
+  "version": "0.1.0",
+  "description": "Search, install and learn AI agent skills from the terminal — powered by the Skills Atlas catalog.",
+  "bin": {
+    "skills-atlas": "bin/skills.js",
+    "sa": "bin/skills.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "data.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "test": "node --test",
+    "prepublishOnly": "node build.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cli",
+    "install",
+    "skills-atlas"
+  ],
+  "license": "MIT",
+  "homepage": "https://zita-go.github.io/Skills-Atlas/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Zita-Go/Skills-Atlas.git",
+    "directory": "packages/skills-atlas-cli"
+  }
+}

package/src/args.js

@@ -0,0 +1,33 @@
+// Thin wrapper over node:util.parseArgs with a shared option dictionary so each
+// command declares only the flags it accepts (typos on others still error).
+'use strict';
+
+const { parseArgs } = require('node:util');
+
+const ALL = {
+  category: { type: 'string', short: 'c' },
+  persona: { type: 'string', short: 'p' },
+  type: { type: 'string', short: 't' },
+  chain: { type: 'boolean' },
+  limit: { type: 'string' },
+  global: { type: 'boolean', short: 'g' },
+  project: { type: 'boolean' },
+  source: { type: 'string', short: 's' },
+  force: { type: 'boolean', short: 'f' },
+  yes: { type: 'boolean', short: 'y' },
+  'dry-run': { type: 'boolean' },
+  json: { type: 'boolean' },
+  en: { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' },
+};
+
+function parse(argv, allowed) {
+  const options = { help: ALL.help, en: ALL.en };
+  for (const k of allowed) {
+    if (!ALL[k]) throw new Error(`unknown option spec: ${k}`);
+    options[k] = ALL[k];
+  }
+  return parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+}
+
+module.exports = { parse };

package/src/commands/categories.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { bold, dim, cyan } = require('../format');
+
+const loose = (hay, needle) =>
+  String(hay || '').toLowerCase().includes(String(needle).toLowerCase());
+
+async function categories(argv) {
+  const { values } = parse(argv, ['json']);
+  if (values.help) { console.log('usage: skills-atlas categories [--json] [--en]'); return; }
+
+  const en = Boolean(values.en);
+  const { data } = loadData({ quiet: values.json });
+  const cats = data.sections.map(s => ({
+    title: en ? (s.title_en || s.title) : s.title,
+    icon: s.icon || '',
+    subgroups: s.subsections.length,
+    groups: s.subsections.reduce((n, ss) => n + ss.rows.length, 0),
+  }));
+
+  if (values.json) { console.log(JSON.stringify(cats, null, 2)); return; }
+  cats.forEach(c =>
+    console.log(`${c.icon} ${bold(c.title)}  ${dim(`(${c.subgroups} subgroups, ${c.groups} groups)`)}`));
+}
+
+async function list(argv) {
+  const { values, positionals } = parse(argv, ['category', 'json']);
+  if (values.help) { console.log('usage: skills-atlas list [category] [--json] [--en]'); return; }
+
+  const en = Boolean(values.en);
+  const filter = (positionals.join(' ') || values.category || '').trim();
+  const { data } = loadData({ quiet: values.json });
+
+  const out = [];
+  for (const s of data.sections) {
+    if (filter && !(loose(s.title, filter) || loose(s.title_en, filter))) continue;
+    out.push({
+      section: en ? (s.title_en || s.title) : s.title,
+      groups: s.subsections.flatMap(ss => ss.rows.map(r => ({
+        group: en ? (r.group_en || r.group) : r.group,
+        skills: r.skills,
+        chain: r.chain,
+      }))),
+    });
+  }
+
+  if (values.json) { console.log(JSON.stringify(out, null, 2)); return; }
+  if (!out.length) {
+    console.error(`no category matching '${filter}'. run: skills-atlas categories`);
+    process.exitCode = 1;
+    return;
+  }
+  for (const sec of out) {
+    console.log(`\n${bold(sec.section)}`);
+    for (const g of sec.groups) {
+      console.log(`  ${g.chain ? cyan('⛓ ') : ''}${g.group}  ${dim(g.skills.join(', '))}`);
+    }
+  }
+}
+
+module.exports = { categories, list };

package/src/commands/info.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, suggestSkills } = require('../index-build');
+const { buildInfo, renderInfo } = require('../format');
+
+const HELP = `usage: skills-atlas info <skill> [--json] [--en]
+
+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.`;
+
+module.exports = async function info(argv) {
+  const { values, positionals } = parse(argv, ['json']);
+  if (values.help) { console.log(HELP); return; }
+
+  const name = positionals[0];
+  if (!name) {
+    console.error('usage: skills-atlas info <skill>');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { data } = loadData({ quiet: values.json });
+  const { skillIndex } = buildIndices(data);
+  const infoObj = buildInfo(name, { skillIndex, vendors: data.vendors });
+
+  if (!infoObj.found) {
+    if (values.json) {
+      console.log(JSON.stringify(infoObj, null, 2));
+    } else {
+      const sugg = suggestSkills(skillIndex, name);
+      console.error(`skill '${name}' not found.`);
+      if (sugg.length) console.error(`did you mean: ${sugg.join(', ')}`);
+      console.error(`try: skills-atlas search ${name}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (values.json) {
+    console.log(JSON.stringify(infoObj, null, 2));
+    return;
+  }
+  console.log(renderInfo(infoObj, { en: Boolean(values.en) }));
+};

package/src/commands/install.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const path = require('path');
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, vendorsFor, suggestSkills, skillDocPath } = require('../index-build');
+const { listSkillFiles, fetchRaw } = require('../github');
+const fsu = require('../fsutil');
+const { confirm, choose } = require('../prompt');
+const { buildInfo, renderInfo, bold, dim, cyan, green, stars } = require('../format');
+
+const HELP = `usage: skills-atlas install <skill> [options]
+
+options:
+  -g, --global       install to ~/.claude/skills/   (default)
+      --project      install to ./.claude/skills/
+  -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)
+      --dry-run      show what would download, write nothing
+      --json         machine-readable output`;
+
+function resolveGlobal(values) {
+  if (values.project) return false;
+  if (values.global) return true;
+  return true; // default: global
+}
+
+module.exports = async function install(argv) {
+  const { values, positionals } = parse(argv,
+    ['global', 'project', 'source', 'force', 'yes', 'dry-run', 'json']);
+  if (values.help) { console.log(HELP); return; }
+
+  const name = positionals[0];
+  if (!name) {
+    console.error('usage: skills-atlas install <skill> [--global|--project] [--source <id>] [--force] [--yes]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { data } = loadData({ quiet: values.json });
+  const idx = buildIndices(data);
+  const candidates = vendorsFor(idx.skillIndex, name); // distinct vendors, best first
+
+  if (candidates.length === 0) {
+    const sugg = suggestSkills(idx.skillIndex, name);
+    console.error(`skill '${name}' not found.`);
+    if (sugg.length) console.error(`did you mean: ${sugg.join(', ')}`);
+    console.error(`try: skills-atlas search ${name}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- pick the source vendor ---
+  let chosen;
+  if (values.source) {
+    chosen = candidates.find(c => c.source.name.toLowerCase() === values.source.toLowerCase());
+    if (!chosen) {
+      console.error(`source '${values.source}' does not provide '${name}'.`);
+      console.error(`available: ${candidates.map(c => c.source.name).join(', ')}`);
+      process.exitCode = 1;
+      return;
+    }
+  } else if (candidates.length === 1 || values.yes) {
+    chosen = candidates[0];
+  } else {
+    const labels = candidates.map(c =>
+      `${c.source.name}  ${stars(c.source.stars)}  ${c.source.type || ''}  ${(c.source.install && c.source.install.command) || ''}`);
+    const i = await choose(`'${name}' is available from ${candidates.length} sources:`, labels);
+    if (i < 0) {
+      console.error(`multiple sources for '${name}'. re-run with --source <id> or --yes.`);
+      console.error(`sources: ${candidates.map(c => c.source.name).join(', ')}`);
+      process.exitCode = 2;
+      return;
+    }
+    chosen = candidates[i];
+  }
+
+  const v = chosen.vendor || {};
+  const src = chosen.source;
+  const skill = chosen.skill || name; // canonical skill name from the index
+  const author = v.author || src.author;
+  const repo = v.repo || src.repo;
+  const branch = v.default_branch || src.default_branch || 'main';
+  const docPath = skillDocPath(v, skill);
+  const installCmd = src.install || v.install || null;
+
+  // --- fallback: no per-skill folder -> whole-repo installer (valid outcome) ---
+  if (!docPath) {
+    if (values.json) {
+      console.log(JSON.stringify({ skill: name, mode: 'whole-repo', source: src.name, install: installCmd }));
+      return;
+    }
+    console.log(`\n'${name}' from ${bold(src.name)} (type=${src.type}) installs the whole repo, not a single folder.`);
+    if (installCmd && installCmd.command) {
+      console.log(`run:\n   ${cyan(installCmd.command)}`);
+      if (installCmd.alt) console.log(`alt:\n   ${installCmd.alt}`);
+      if (installCmd.note) console.log(dim('   ' + installCmd.note));
+    } else {
+      console.log(`see ${src.url}`);
+    }
+    return; // exit 0
+  }
+
+  if (!author || !repo) {
+    console.error(`missing author/repo for source '${src.name}'; cannot download.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const targetRoot = fsu.installTargetDir({ global: resolveGlobal(values) });
+  const dest = path.join(targetRoot, skill); // folder = skill name (strips repo nesting)
+
+  // --- already installed? ---
+  if (fsu.dirExists(dest) && !values['dry-run']) {
+    if (!values.force) {
+      if (values.yes) {
+        console.error(`'${name}' already installed at ${fsu.tildify(dest)} (use --force to overwrite).`);
+        process.exitCode = 1;
+        return;
+      }
+      const ok = await confirm(`${fsu.tildify(dest)} exists. overwrite?`, false);
+      if (!ok) { console.log('aborted.'); return; }
+    }
+  }
+
+  // --- list the skill folder's files ---
+  let listing;
+  try {
+    listing = await listSkillFiles({ author, repo, branch, docPath });
+  } catch (e) {
+    console.error(`failed to read ${author}/${repo}: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (values['dry-run']) {
+    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));
+    return;
+  }
+
+  // --- download into a tmp dir, then atomically swap into place ---
+  const tmp = fsu.mkdtemp();
+  try {
+    for (const f of listing.files) {
+      const buf = await fetchRaw(author, repo, listing.branchUsed, f.path);
+      fsu.writeFileMkdir(path.join(tmp, f.rel), buf);
+    }
+    const hasSkillMd = listing.files.some(f => {
+      const rel = f.rel.toLowerCase();
+      return rel === 'skill.md' || rel.endsWith('/skill.md');
+    });
+    if (!hasSkillMd) throw new Error('no SKILL.md found in downloaded folder');
+    fsu.swapDir(tmp, dest);
+  } catch (e) {
+    fsu.rmrf(tmp);
+    console.error(`install failed: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (values.json) {
+    console.log(JSON.stringify({
+      skill: name, mode: 'folder', source: src.name,
+      dest, files: listing.files.length, branch: listing.branchUsed,
+    }));
+    return;
+  }
+
+  console.log(`\n${green('✓')} installed ${bold(skill)} → ${fsu.tildify(dest)}  ${dim(`(${listing.files.length} file(s) from ${src.name}@${listing.branchUsed})`)}`);
+  if (listing.note) console.log(dim('  ' + listing.note));
+
+  // usage guidance
+  const infoObj = buildInfo(skill, { skillIndex: idx.skillIndex, vendors: data.vendors });
+  console.log(renderInfo(infoObj, { en: Boolean(values.en) }));
+  console.log(dim('\nStart a new Claude Code session to load the skill, then invoke it by name.'));
+};

package/src/commands/search.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices } = require('../index-build');
+const { searchRows } = require('../search-core');
+const { renderRow } = require('../format');
+
+const HELP = `usage: skills-atlas search <query...> [filters]
+
+Matches by words, not whole-string: multiple keywords and loose phrases work
+(e.g. "pdf 翻译", "translate a whole pdf"). Ranked by how many terms hit.
+
+filters:
+  -c, --category <s>   match a top-level category (loose, zh or en)
+  -p, --persona <s>    match a persona (工程/PM/设计/研究/运营/营销/...)
+  -t, --type <s>       match a source type (skill/plugin/marketplace/...)
+      --chain          only ⛓ strong-binding workflow chains
+      --limit <n>      max results (default 15)
+      --json           machine-readable output
+      --en             English output`;
+
+function jsonRow(r) {
+  return {
+    group: r.group, group_en: r.group_en, category: r._cat, chain: r.chain,
+    skills: r.skills, use_case: r.use_case, when_to_use: r.when_to_use,
+    personas: r.personas || [],
+    sources: (r.sources || []).map(s => ({
+      id: s.name, stars: s.stars, type: s.type,
+      install: s.install ? s.install.command : null,
+    })),
+  };
+}
+
+module.exports = async function search(argv) {
+  const { values, positionals } = parse(argv, ['category', 'persona', 'type', 'chain', 'limit', 'json']);
+  if (values.help) { console.log(HELP); return; }
+
+  const query = positionals.join(' ').trim();
+  const hasFilter = values.category || values.persona || values.type || values.chain;
+  if (!query && !hasFilter) {
+    console.error('usage: skills-atlas search <query...> [-c category] [-p persona] [-t type] [--chain]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const en = Boolean(values.en);
+  const { data } = loadData({ quiet: values.json });
+  const { flatRows } = buildIndices(data);
+
+  const rows = searchRows(flatRows, {
+    query,
+    category: values.category,
+    persona: values.persona,
+    type: values.type,
+    chain: values.chain,
+  });
+
+  const limit = Math.max(1, parseInt(values.limit || '15', 10) || 15);
+  const shown = rows.slice(0, limit);
+
+  if (values.json) {
+    console.log(JSON.stringify(shown.map(jsonRow), null, 2));
+    return;
+  }
+  shown.forEach(r => console.log(renderRow(r, { en })));
+  const more = rows.length > limit ? `, showing ${limit}` : '';
+  console.log(`\n${rows.length} match(es)${more}.`);
+};

package/src/commands/update.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { parse } = require('../args');
+const { refreshData } = require('../data');
+
+module.exports = async function update(argv) {
+  const { values } = parse(argv, ['json']);
+  if (values.help) {
+    console.log('usage: skills-atlas update\n\nRefresh the local catalog cache from the public data feed.');
+    return;
+  }
+
+  try {
+    const res = await refreshData();
+    if (values.json) { console.log(JSON.stringify(res, null, 2)); return; }
+    if (!res.changed) {
+      console.log(`catalog already up to date (${res.counts.vendors} vendors, ${res.counts.groups} groups).`);
+      return;
+    }
+    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

@@ -0,0 +1,150 @@
+// Data loading + caching for the Skills Atlas catalog.
+//
+// Offline-first: normal commands (search/info/install) never hit the network —
+// they read a refreshed cache if present, otherwise the bundled snapshot. Only
+// `update` fetches from the public URL.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PUBLIC_URL = 'https://zita-go.github.io/Skills-Atlas/data.json';
+const UA = 'skills-atlas-cli';
+const STALE_DAYS = 30;
+
+function cacheDir() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'skills-atlas');
+}
+const cacheFile = () => path.join(cacheDir(), 'data.json');
+const metaFile = () => path.join(cacheDir(), 'meta.json');
+
+function tryReadJSON(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isValid(d) {
+  return d && Array.isArray(d.sections) && d.vendors && typeof d.vendors === 'object';
+}
+
+function counts(d) {
+  const groups = d.sections.reduce(
+    (n, s) => n + s.subsections.reduce((m, ss) => m + ss.rows.length, 0), 0);
+  return { sections: d.sections.length, groups, vendors: Object.keys(d.vendors).length };
+}
+
+// Resolve the bundled (offline) snapshot. Works when published (own ./data.json
+// shipped in `files`) and in the monorepo during dev (sibling data package or
+// the canonical docs/data.json), so it never hard-fails before `npm run build`.
+function loadBundled() {
+  const candidates = [
+    path.join(__dirname, '..', 'data.json'),                         // copied by build.js
+    path.join(__dirname, '..', '..', 'skills-atlas-data', 'data.json'), // sibling package (dev)
+    path.join(__dirname, '..', '..', '..', 'docs', 'data.json'),     // canonical (dev)
+  ];
+  for (const p of candidates) {
+    const d = tryReadJSON(p);
+    if (isValid(d)) return { data: d, source: p };
+  }
+  try {
+    const d = require('skills-atlas-data'); // npm dependency, if installed
+    if (isValid(d)) return { data: d, source: 'skills-atlas-data' };
+  } catch { /* not installed */ }
+  throw new Error(
+    'No Skills Atlas data found. Run `npm run build` in packages/skills-atlas-cli, ' +
+    'or run `skills-atlas update` to fetch the catalog.');
+}
+
+// One-line stderr nudge when the catalog is the bundled snapshot or a stale cache.
+function maybeStaleNudge(fromCache) {
+  const meta = tryReadJSON(metaFile());
+  let stale = true;
+  if (fromCache && meta && meta.fetchedAt) {
+    const ageDays = (Date.now() - Date.parse(meta.fetchedAt)) / 86400000;
+    stale = !(ageDays >= 0 && ageDays < STALE_DAYS);
+  }
+  if (stale) {
+    process.stderr.write("tip: run 'skills-atlas update' to refresh the catalog\n");
+  }
+}
+
+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 };
+}
+
+function ensureDir(d) {
+  fs.mkdirSync(d, { recursive: true });
+}
+
+// Fetch the public catalog and atomically replace the cache. Never corrupts the
+// existing cache on failure (validate + tmp-then-rename).
+async function refreshData() {
+  const meta = tryReadJSON(metaFile()) || {};
+  const headers = { 'User-Agent': UA, Accept: 'application/json' };
+  if (meta.etag) headers['If-None-Match'] = meta.etag;
+
+  const prev = tryReadJSON(cacheFile());
+  let res;
+  const ac = new AbortController();
+  const timeoutMs = Number(process.env.SKILLS_ATLAS_TIMEOUT_MS) || 25000;
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    res = await fetch(PUBLIC_URL, { headers, signal: ac.signal });
+  } catch (e) {
+    throw new Error(e.name === 'AbortError'
+      ? `timed out after ${timeoutMs}ms fetching catalog`
+      : `network error fetching catalog: ${e.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (res.status === 304 && isValid(prev)) {
+    return { changed: false, counts: counts(prev), url: PUBLIC_URL };
+  }
+  if (!res.ok) {
+    throw new Error(`fetch failed: HTTP ${res.status} ${res.statusText} (${PUBLIC_URL})`);
+  }
+
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error('downloaded catalog is not valid JSON; kept existing cache');
+  }
+  if (!isValid(data)) {
+    throw new Error('downloaded catalog missing sections/vendors; kept existing cache');
+  }
+
+  ensureDir(cacheDir());
+  const tmp = cacheFile() + '.tmp';
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, cacheFile());
+  fs.writeFileSync(metaFile(), JSON.stringify({
+    fetchedAt: new Date().toISOString(),
+    etag: res.headers.get('etag') || null,
+    sourceUrl: PUBLIC_URL,
+    counts: counts(data),
+  }, null, 2));
+
+  return {
+    changed: true,
+    counts: counts(data),
+    prevCounts: isValid(prev) ? counts(prev) : null,
+    url: PUBLIC_URL,
+  };
+}
+
+module.exports = { loadData, refreshData, counts, cacheDir, PUBLIC_URL };