agentskillsdk 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentskillsdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Install agent skills from agentskills.dk",
   "type": "module",
   "bin": {

package/src/commands/add.js

@@ -4,7 +4,6 @@ import { join } from 'node:path';
 import { fetchSkill, fetchSkills } from '../lib/api.js';
 import { detectAgents, AGENTS, AGENT_BY_SLUG } from '../lib/detect-agent.js';
 import { downloadSkill } from '../lib/download.js';
-import { resolveGithubSkillPath } from '../lib/resolve-github-path.js';
 import { parseSource } from '../lib/parse-source.js';
 import { selectPrompt, checkboxPrompt } from '../lib/prompt.js';
 import { createOutput } from '../lib/output.js';
@@ -178,42 +177,19 @@ export async function addCommand(skillName, options = {}) {
     else msgKey = 'add.source.github';
     out.step(t(msgKey, { owner: parsed.owner, repo: parsed.repo, ref: parsed.ref, skill: requestedPath }));
 
-    // Resolve the requested path against the actual repo layout. The website's
-    // registry runs `matchSkillToPath` during indexing for the same reason —
-    // users type `--skill foo` but the file lives at `skills/foo/SKILL.md`.
-    //
-    // Only resolve when the caller asked for a specific skill — for bare
-    // `owner/repo` we preserve the existing "install whatever's in the tarball"
-    // behavior so registry-style installs and single-skill repos still work.
-    let skillPath = requestedPath;
-    if (requestedPath) {
-      const lookup = out.spinner(t('add.spinner.resolving_path'));
-      let resolved;
-      try {
-        resolved = await resolveGithubSkillPath({
-          owner: parsed.owner,
-          repo: parsed.repo,
-          ref: parsed.ref,
-          requestedPath,
-        });
-      } catch (err) {
-        lookup.fail(t('add.error.resolve_fail'));
-        throw err;
-      }
-      if (resolved.resolved) {
-        lookup.succeed(t('add.spinner.resolved_path', { from: requestedPath, to: resolved.path }));
-      } else {
-        lookup.succeed(t('add.spinner.path_ok'));
-      }
-      skillPath = resolved.path;
-    }
-    installName = skillPath ? skillPath.split('/').pop() : parsed.repo;
+    // installName is derived from the requested skill so the on-disk folder
+    // matches what the user typed (`--skill ai-seo` → `.claude/skills/ai-seo/`),
+    // even when the actual source path inside the repo is nested
+    // (`skills/ai-seo/`). The real path is resolved inside downloadSkill from
+    // the tarball itself — no GitHub API call needed.
+    installName = requestedPath ? requestedPath.split('/').pop() : parsed.repo;
     skill = {
       name: installName,
       githubOwner: parsed.owner,
       githubRepo: parsed.repo,
-      githubPath: skillPath || undefined,
+      githubPath: requestedPath || undefined,
       ref: parsed.ref,
+      requestedPath,
     };
   } else {
     installName = parsed.name;
@@ -311,9 +287,14 @@ export async function addCommand(skillName, options = {}) {
   }
 
   const spinner = out.spinner(t('add.spinner.downloading'));
+  let lastResolved;
   try {
     for (const { destDir } of destPlan) {
-      await downloadSkill(skill, destDir);
+      const result = await downloadSkill(skill, destDir, {
+        requestedPath: skill.requestedPath,
+        owner: skill.githubOwner,
+      });
+      lastResolved = result;
     }
   } catch (err) {
     spinner.fail(t('add.error.download_fail'));
@@ -321,6 +302,19 @@ export async function addCommand(skillName, options = {}) {
   }
   spinner.succeed(t('add.spinner.downloaded'));
 
+  // If the resolver picked a different path than the user asked for, surface
+  // it so they understand where the files actually came from.
+  if (isGithub && lastResolved && skill.requestedPath && lastResolved.resolvedPath !== skill.requestedPath) {
+    out.step(t('add.spinner.resolved_path', {
+      from: skill.requestedPath,
+      to: lastResolved.resolvedPath,
+    }));
+  }
+  if (isGithub && lastResolved) {
+    // Update the JSON `source.path` to reflect what was actually installed.
+    sourcePayload.path = lastResolved.resolvedPath || undefined;
+  }
+
   const agentsWithPath = agents.map(a => ({
     slug: a.slug,
     name: a.name,

package/src/lib/download.js

@@ -1,12 +1,37 @@
 import { pipeline } from 'node:stream/promises';
 import { createGunzip } from 'node:zlib';
-import { createWriteStream, mkdirSync } from 'node:fs';
+import { writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
 import tar from 'tar-stream';
 import { NetworkError, FsError, NoMatchError } from './errors.js';
+import { matchSkillDir } from './resolve-github-path.js';
 import { t } from './messages/index.js';
 
-export async function downloadSkill(skill, destDir) {
+const PER_ENTRY_SIZE_CAP = 25 * 1024 * 1024; // 25 MB
+
+function stripFirstSegment(p) {
+  const parts = p.split('/');
+  parts.shift();
+  return parts.join('/');
+}
+
+function isSkillMd(name) {
+  return /(^|\/)SKILL\.md$/i.test(name);
+}
+
+// Downloads a GitHub tarball, resolves which skill directory inside it to
+// install, and writes the matching files to `destDir`. Path resolution is
+// done entirely from the tarball contents — no GitHub API calls — so this
+// works under anonymous-IP rate limits (the resolver previously hit 403 in
+// shared cloud sandboxes).
+//
+// Returns { resolvedPath, skillDirs } so the caller can log "resolved A → B".
+export async function downloadSkill(skill, destDir, opts = {}) {
+  // Backward-compat: when callers don't pass an opts object, fall back to the
+  // legacy `skill.githubPath` field. Production code in add.js passes opts
+  // explicitly; this fallback exists for unit tests that pre-date the change.
+  const requestedPath = opts.requestedPath ?? skill.githubPath;
+  const owner = opts.owner ?? skill.githubOwner;
   const base = `https://api.github.com/repos/${skill.githubOwner}/${skill.githubRepo}/tarball`;
   const url = skill.ref ? `${base}/${skill.ref}` : base;
 
@@ -22,17 +47,12 @@ export async function downloadSkill(skill, destDir) {
   } catch {
     throw new NetworkError(t('download.error.network'));
   }
-
   if (!res.ok) throw new NetworkError(t('download.error.github', { status: res.status }));
 
   const extract = tar.extract();
-  const skillPath = skill.githubPath || '';
-  const destDirResolved = resolve(destDir);
+  const entries = new Map(); // relativePath -> Buffer
   let aborted = null;
-  let filesWritten = 0;
 
-  // Swallow late errors after we've already captured `aborted`; pipeline()
-  // will surface the original failure.
   extract.on('error', () => {});
 
   extract.on('entry', (header, stream, next) => {
@@ -42,88 +62,133 @@ export async function downloadSkill(skill, destDir) {
       return;
     }
 
-    // Reject symlink/link entries outright.
-    if (header.type === 'symlink' || header.type === 'link') {
-      aborted = new FsError(t('download.error.unsupported_entry', { type: header.type, name: header.name }));
-      stream.on('end', () => next(aborted));
-      stream.resume();
-      return;
-    }
-
-    // Tarball entries: "{owner}-{repo}-{sha}/skills/real-estate-crm/SKILL.md"
-    // Strip the first path segment (the repo prefix).
-    const parts = header.name.split('/');
-    parts.shift();
-    const relativePath = parts.join('/');
-
-    let fileRelative;
-    if (skillPath === '') {
-      if (header.type === 'file' && relativePath) {
-        fileRelative = relativePath;
-      }
-    } else {
-      if (header.type === 'file' && relativePath.startsWith(skillPath + '/')) {
-        fileRelative = relativePath.slice(skillPath.length + 1);
-      }
-    }
-
-    if (!fileRelative) {
+    // Skip symlinks and hardlinks. We never write them to disk, so they can't
+    // cause harm — but real-world skill repos use symlinks to deduplicate
+    // shared docs (e.g. CLAUDE.md alias). Aborting the whole install over a
+    // symlink in an unrelated skill made multi-skill repos uninstallable.
+    if (header.type !== 'file') {
       stream.on('end', next);
       stream.resume();
       return;
     }
 
-    const destPath = join(destDir, fileRelative);
-    const destPathResolved = resolve(destPath);
-
-    // Zip-slip guard: destination must stay within destDir.
-    if (destPathResolved !== destDirResolved && !destPathResolved.startsWith(destDirResolved + sep)) {
-      aborted = new FsError(t('download.error.traversal', { name: header.name }));
-      stream.on('end', () => next(aborted));
+    const relativePath = stripFirstSegment(header.name);
+    if (!relativePath) {
+      stream.on('end', next);
       stream.resume();
       return;
     }
 
-    mkdirSync(dirname(destPathResolved), { recursive: true });
-
-    const ws = createWriteStream(destPathResolved);
-    let finished = false;
-    ws.on('finish', () => {
-      finished = true;
-      filesWritten++;
-      next();
+    const chunks = [];
+    let size = 0;
+    stream.on('data', (c) => {
+      size += c.length;
+      if (size > PER_ENTRY_SIZE_CAP && !aborted) {
+        aborted = new FsError(t('download.error.entry_too_large', {
+          name: header.name,
+          cap: PER_ENTRY_SIZE_CAP,
+        }));
+      }
+      if (!aborted) chunks.push(c);
     });
-    ws.on('error', (err) => {
-      if (!aborted) aborted = err instanceof FsError ? err : new FsError(err.message);
-      if (!finished) next();
+    stream.on('end', () => {
+      if (!aborted) entries.set(relativePath, Buffer.concat(chunks));
+      next();
     });
     stream.on('error', (err) => {
       if (!aborted) aborted = err instanceof FsError ? err : new FsError(err.message);
     });
-    stream.pipe(ws);
   });
 
   try {
-    await pipeline(
-      res.body,
-      createGunzip(),
-      extract,
-    );
+    await pipeline(res.body, createGunzip(), extract);
   } catch (err) {
     if (aborted) throw aborted;
     throw err;
   }
-
   if (aborted) throw aborted;
 
-  // Defense in depth: even with upfront path resolution, refuse to report a
-  // successful install when zero files were written. Previously the CLI would
-  // print a success banner with a path that didn't exist on disk.
+  // Discover skill directories from the buffered tarball.
+  const skillDirs = [...new Set(
+    [...entries.keys()]
+      .filter(isSkillMd)
+      .map(p => p.replace(/\/?SKILL\.md$/i, '')),
+  )];
+
+  // Choose which prefix to install.
+  let prefix;
+  if (requestedPath) {
+    if (skillDirs.includes(requestedPath)) {
+      prefix = requestedPath;
+    } else {
+      prefix = matchSkillDir(requestedPath, owner || skill.githubOwner, skillDirs);
+    }
+    if (prefix === null || prefix === undefined) {
+      throw new NoMatchError(t('resolve.error.skill_not_in_repo', {
+        skill: requestedPath,
+        owner: skill.githubOwner,
+        repo: skill.githubRepo,
+        candidates: skillDirs.length > 0
+          ? skillDirs.map(d => `  - ${d || '<root>'}`).join('\n')
+          : '  (no SKILL.md files found in this repo)',
+      }));
+    }
+  } else {
+    if (skillDirs.length === 0) {
+      throw new NoMatchError(t('resolve.error.no_skills', {
+        owner: skill.githubOwner,
+        repo: skill.githubRepo,
+      }));
+    }
+    if (skillDirs.length > 1) {
+      throw new NoMatchError(t('resolve.error.multiple_skills', {
+        owner: skill.githubOwner,
+        repo: skill.githubRepo,
+        candidates: skillDirs.map(d => `  - ${d || '<root>'}`).join('\n'),
+      }));
+    }
+    prefix = skillDirs[0];
+  }
+
+  // Write files under the resolved prefix.
+  const destDirResolved = resolve(destDir);
+  let filesWritten = 0;
+
+  for (const [relativePath, buf] of entries) {
+    let fileRelative;
+    if (prefix === '') {
+      fileRelative = relativePath;
+    } else if (relativePath === prefix) {
+      // Edge case: a file literally at the prefix path. Shouldn't happen for
+      // a SKILL.md dir but keep it safe.
+      fileRelative = relativePath.split('/').pop();
+    } else if (relativePath.startsWith(prefix + '/')) {
+      fileRelative = relativePath.slice(prefix.length + 1);
+    } else {
+      continue;
+    }
+    if (!fileRelative) continue;
+
+    const destPath = join(destDir, fileRelative);
+    const destPathResolved = resolve(destPath);
+
+    // Zip-slip guard: destination must stay within destDir.
+    if (destPathResolved !== destDirResolved && !destPathResolved.startsWith(destDirResolved + sep)) {
+      throw new FsError(t('download.error.traversal', { name: relativePath }));
+    }
+
+    mkdirSync(dirname(destPathResolved), { recursive: true });
+    writeFileSync(destPathResolved, buf);
+    filesWritten++;
+  }
+
   if (filesWritten === 0) {
     throw new NoMatchError(t('download.error.no_files_matched', {
-      path: skillPath || '<root>',
+      path: prefix || '<root>',
       owner: skill.githubOwner,
       repo: skill.githubRepo,
     }));
   }
+
+  return { resolvedPath: prefix, skillDirs };
 }

package/src/lib/messages/da.js

@@ -26,10 +26,7 @@ export const da = {
   'add.spinner.downloading': 'downloader skill-filer...',
   'add.error.download_fail': 'download fejlede',
   'add.spinner.downloaded': 'skill-filer downloadet',
-  'add.spinner.resolving_path': 'finder skill-sti i repo...',
   'add.spinner.resolved_path': 'matchede "{from}" → "{to}"',
-  'add.spinner.path_ok': 'skill-sti bekræftet',
-  'add.error.resolve_fail': 'kunne ikke finde skill-stien',
   'add.source.github': 'GitHub-kilde: {owner}/{repo}',
   'add.source.github_with_skill': 'GitHub-kilde: {owner}/{repo} (skill: {skill})',
   'add.source.github_with_ref': 'GitHub-kilde: {owner}/{repo}@{ref}',
@@ -67,6 +64,7 @@ export const da = {
   'download.error.traversal': 'afviste usikker tarball-fil (sti-traversal): {name}',
   'download.error.unsupported_entry': 'afviste ikke-understøttet tarball-fil ({type}): {name}',
   'download.error.no_files_matched': 'ingen filer fundet på stien "{path}" i {owner}/{repo}',
+  'download.error.entry_too_large': 'tarball-fil overstiger størrelsesgrænse ({cap} bytes): {name}',
 
   'resolve.error.no_skills': 'ingen SKILL.md-filer fundet i {owner}/{repo}',
   'resolve.error.multiple_skills': '{owner}/{repo} indeholder flere skills — angiv --skill <navn>:\n{candidates}',

package/src/lib/messages/en.js

@@ -26,10 +26,7 @@ export const en = {
   'add.spinner.downloading': 'downloading skill files...',
   'add.error.download_fail': 'download failed',
   'add.spinner.downloaded': 'skill files downloaded',
-  'add.spinner.resolving_path': 'resolving skill path in repo...',
   'add.spinner.resolved_path': 'resolved "{from}" → "{to}"',
-  'add.spinner.path_ok': 'skill path verified',
-  'add.error.resolve_fail': 'could not resolve skill path',
   'add.source.github': 'GitHub source: {owner}/{repo}',
   'add.source.github_with_skill': 'GitHub source: {owner}/{repo} (skill: {skill})',
   'add.source.github_with_ref': 'GitHub source: {owner}/{repo}@{ref}',
@@ -67,6 +64,7 @@ export const en = {
   'download.error.traversal': 'refused unsafe tarball entry (path traversal): {name}',
   'download.error.unsupported_entry': 'refused unsupported tarball entry type ({type}): {name}',
   'download.error.no_files_matched': 'no files found at path "{path}" in {owner}/{repo}',
+  'download.error.entry_too_large': 'tarball entry exceeds size cap ({cap} bytes): {name}',
 
   'resolve.error.no_skills': 'no SKILL.md files found in {owner}/{repo}',
   'resolve.error.multiple_skills': '{owner}/{repo} contains multiple skills — pass --skill <name>:\n{candidates}',

package/src/lib/resolve-github-path.js

@@ -1,57 +1,10 @@
-import { NetworkError, NoMatchError } from './errors.js';
-import { t } from './messages/index.js';
-
-// Fetches every path in a GitHub repo tree that ends in SKILL.md.
-// Returns the directory paths (without the trailing "/SKILL.md").
-//
-// `ref` is optional — when omitted GitHub resolves the default branch.
-export async function fetchRepoSkillDirs(owner, repo, ref) {
-  const refOrDefault = ref || (await fetchDefaultBranch(owner, repo));
-  const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${encodeURIComponent(refOrDefault)}?recursive=1`;
-
-  let res;
-  try {
-    res = await fetch(url, {
-      headers: {
-        'Accept': 'application/vnd.github+json',
-        'User-Agent': 'agentskillsdk-cli',
-      },
-    });
-  } catch {
-    throw new NetworkError(t('download.error.network'));
-  }
-  if (!res.ok) throw new NetworkError(t('download.error.github', { status: res.status }));
-
-  const json = await res.json();
-  const tree = Array.isArray(json.tree) ? json.tree : [];
-  return tree
-    .filter(e => e.type === 'blob' && /(^|\/)SKILL\.md$/i.test(e.path))
-    .map(e => e.path.replace(/\/?SKILL\.md$/i, ''));
-}
-
-async function fetchDefaultBranch(owner, repo) {
-  let res;
-  try {
-    res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
-      headers: {
-        'Accept': 'application/vnd.github+json',
-        'User-Agent': 'agentskillsdk-cli',
-      },
-    });
-  } catch {
-    throw new NetworkError(t('download.error.network'));
-  }
-  if (!res.ok) throw new NetworkError(t('download.error.github', { status: res.status }));
-  const json = await res.json();
-  return json.default_branch || 'main';
-}
-
 // Picks the best matching skill directory for `requested` from `candidates`.
 // Strategies, in order:
-//   1. Exact directory name match
-//   2. Owner-prefix stripped match (vercel-foo → foo)
-//   3. Fuzzy normalized match (case + non-alphanum collapsed)
-//   4. Single-candidate fallback when only one skill exists
+//   1. Exact last-segment match (case-insensitive)
+//   2. Full-path match (user passed "skills/foo")
+//   3. Owner-prefix stripped match (vercel-foo → foo)
+//   4. Fuzzy normalized match (case + non-alphanum collapsed)
+//   5. Single-candidate fallback when only one skill exists
 // Returns the matched directory path, or null if no match.
 //
 // Ported from the agentskills website's `matchSkillToPath` so behavior stays
@@ -100,42 +53,3 @@ export function matchSkillDir(requested, owner, candidates) {
 
   return null;
 }
-
-// High-level helper used by `add`. Resolves a user-provided `requestedPath`
-// against the actual repo layout. Returns:
-//   - the requested path unchanged if it directly contains a SKILL.md
-//   - the matched directory otherwise
-//   - throws NoMatchError if nothing matches
-export async function resolveGithubSkillPath({ owner, repo, ref, requestedPath }) {
-  const dirs = await fetchRepoSkillDirs(owner, repo, ref);
-
-  // No requested path: only succeed if the repo has exactly one skill.
-  if (!requestedPath) {
-    if (dirs.length === 0) {
-      throw new NoMatchError(t('resolve.error.no_skills', { owner, repo }));
-    }
-    if (dirs.length === 1) return { path: dirs[0], resolved: dirs[0] !== '' };
-    throw new NoMatchError(t('resolve.error.multiple_skills', {
-      owner, repo, candidates: dirs.map(d => `  - ${d || '<root>'}`).join('\n'),
-    }));
-  }
-
-  // Direct hit: the user-supplied path already names a SKILL.md directory.
-  if (dirs.includes(requestedPath)) {
-    return { path: requestedPath, resolved: false };
-  }
-
-  const matched = matchSkillDir(requestedPath, owner, dirs);
-  if (matched === null) {
-    throw new NoMatchError(t('resolve.error.skill_not_in_repo', {
-      skill: requestedPath,
-      owner,
-      repo,
-      candidates: dirs.length > 0
-        ? dirs.map(d => `  - ${d || '<root>'}`).join('\n')
-        : '  (no SKILL.md files found in this repo)',
-    }));
-  }
-
-  return { path: matched, resolved: matched !== requestedPath };
-}