skills-atlas-cli 0.1.1 → 0.1.2

package/README.md

@@ -59,16 +59,21 @@ 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.
 
-- Unlike `git clone`, it fetches **only that skill's folder**, not the whole repo.
+On top of that, `install` can place a skill straight into `.claude/skills/`:
+
+- 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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

@@ -7,7 +7,7 @@ const { buildIndices, vendorsFor, suggestSkills, skillDocPath } = require('../in
 const { listSkillFiles, fetchRaw, fetchSkillFolderTar } = require('../github');
 const fsu = require('../fsutil');
 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]
 
@@ -20,8 +20,9 @@ options:
       --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;
@@ -79,6 +80,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
@@ -138,6 +150,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));
@@ -149,7 +170,7 @@ module.exports = async function install(argv) {
   // 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;
+  let branchUsed, fileCount, note = null, scripts = [];
   try {
     let folder = null;
     try {
@@ -180,6 +201,7 @@ module.exports = async function install(argv) {
     });
     if (!hasSkillMd) throw new Error('no SKILL.md found in downloaded folder');
     fileCount = rels.length;
+    scripts = fsu.scriptFiles(rels);
     fsu.swapDir(tmp, dest);
   } catch (e) {
     fsu.rmrf(tmp);
@@ -191,16 +213,23 @@ 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,
+      dest, files: fileCount, scripts: scripts.length, branch: 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}`));
+  }
 
-  // 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/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/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]);