agentskillsdk 0.5.2 → 0.6.0

package/src/lib/messages/en.js

@@ -0,0 +1,98 @@
+export const en = {
+  'banner.subtitle': 'install skills for AI agents',
+
+  'add.error.both_flags': 'cannot use both --global and --project',
+  'add.error.dest_exists': 'destination already exists: {path} (use --force to overwrite)',
+  'add.dry_run.header': 'dry-run — no files will be written',
+  'add.dry_run.would_write': 'would write to {path}',
+  'add.dry_run.scope': 'scope: {scope}',
+  'add.dry_run.source': 'source: {source}',
+  'add.step.removing_existing': 'removing existing {path}...',
+  'add.spinner.lookup': 'looking up {name}...',
+  'add.error.registry_fail': 'registry lookup failed',
+  'add.error.not_found': 'skill not found: {name}',
+  'add.suggest.header': 'did you mean:',
+  'add.suggest.browse': 'browse all skills:',
+  'add.spinner.found': 'found skill: {name}',
+  'add.prompt.how_install': 'how would you like to install?',
+  'add.prompt.all_detected': 'all detected agents ({count})',
+  'add.prompt.choose_specific': 'choose specific agents',
+  'add.prompt.select_agents': 'select agents:',
+  'add.prompt.scope': 'install scope for "{name}":',
+  'add.prompt.scope_project': 'project',
+  'add.prompt.scope_project_hint': '(local {folder}/skills/)',
+  'add.prompt.scope_global': 'global',
+  'add.prompt.scope_global_hint': '(~/{folder}/skills/)',
+  '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}',
+  'add.source.github_with_ref_and_skill': 'GitHub source: {owner}/{repo}@{ref} (skill: {skill})',
+  'add.step.agent_single': 'agent: {name}',
+  'add.step.agent_multi': 'agents: {names}',
+
+  'summary.title': 'skill installed!',
+  'summary.skill': 'skill:',
+  'summary.scope': 'scope:',
+  'summary.scope_global': 'global (all projects)',
+  'summary.scope_project': 'project (local)',
+  'summary.agent': 'agent:',
+  'summary.agents': 'agents:',
+  'summary.path': 'path:',
+  'summary.paths': 'paths:',
+  'summary.session_single': 'start a new {agent} session to use it.',
+  'summary.session_multi': 'start a new session in one of these agents to use it.',
+  'summary.learn_more': 'learn more:',
+
+  'hints.select': '↑↓ navigate · enter select · esc back',
+  'hints.checkbox': '↑↓ navigate · space toggle · enter confirm · esc back',
+
+  'list.empty': 'no skills available yet.',
+  'list.header': 'available skills:',
+  'list.install': 'install:',
+  'list.browse': 'browse:',
+
+  'api.error.unreachable': 'could not reach agentskills.dk. check your internet connection.',
+  'api.error.fetch_skills': 'failed to fetch skills: {status}',
+  'api.error.fetch_skill': 'failed to fetch skill: {status}',
+
+  'download.error.network': 'could not download skill files. check your internet connection.',
+  'download.error.github': 'GitHub download failed: {status}',
+  '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}',
+
+  '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}',
+  'resolve.error.skill_not_in_repo': 'skill "{skill}" not found in {owner}/{repo}. available skills:\n{candidates}',
+
+  'cli.description': 'install agent skills from agentskills.dk',
+  'cli.add.description': 'install a skill in your project',
+  'cli.add.arg': 'skill name (or owner/repo for GitHub)',
+  'cli.add.skill_option': 'subpath in repo, e.g. skills/twitter',
+  'cli.add.global_option': 'install globally in ~/.claude/skills/',
+  'cli.add.project_option': 'install in project .claude/skills/ (default)',
+  'cli.add.yes_option': 'skip prompts (required in agent contexts)',
+  'cli.add.non_interactive_option': 'alias for --yes',
+  'cli.add.agent_option': "target agent slug(s), e.g. -a claude-code -a cursor (use '*' for all)",
+  'cli.add.all_option': "target every known agent (alias for -a '*')",
+  'cli.add.json_option': 'machine-readable JSON on stdout',
+  'cli.add.quiet_option': 'suppress banner and spinners',
+  'cli.add.lang_option': 'UI language (en|da)',
+  'cli.add.dry_run_option': 'show planned writes without touching disk',
+  'cli.add.force_option': 'overwrite existing skill directory',
+  'cli.list.description': 'list all available skills',
+
+  'error.no_tty_no_yes': 'non-interactive context: pass --yes (-y) and required flags',
+  'error.unknown_agent_slug': 'unknown agent slug: {slug}',
+  'error.ambiguous_agent': 'multiple agents detected — pass --agent to disambiguate ({candidates})',
+  'error.no_agent_target': 'no agent target — pass --agent or run in a project with one of: {candidates}',
+  'error.canceled': 'cancelled',
+  'agent.folder_created': 'created {folder} for {name}',
+};

package/src/lib/messages/index.js

@@ -0,0 +1,49 @@
+import { en } from './en.js';
+import { da } from './da.js';
+
+const LOCALES = { en, da };
+let currentLocale = 'en';
+let warnedUnknown = false;
+
+export function setLocale(locale) {
+  if (!locale) return;
+  if (LOCALES[locale]) {
+    currentLocale = locale;
+    return;
+  }
+  if (!warnedUnknown) {
+    process.stderr.write(`agentskillsdk: unknown --lang "${locale}", falling back to en\n`);
+    warnedUnknown = true;
+  }
+  currentLocale = 'en';
+}
+
+export function getLocale() {
+  return currentLocale;
+}
+
+// Resolution order: explicit flag > AGENTSKILLSDK_LANG > 'en'.
+export function resolveLocale({ flag, env = process.env } = {}) {
+  return flag || env.AGENTSKILLSDK_LANG || 'en';
+}
+
+export function t(key, params) {
+  let value = LOCALES[currentLocale]?.[key];
+  if (value === undefined && currentLocale !== 'en') value = LOCALES.en[key];
+  if (value === undefined) {
+    if (process.env.NODE_ENV === 'test') {
+      process.stderr.write(`agentskillsdk: missing message key "${key}"\n`);
+    }
+    return key;
+  }
+  if (!params) return value;
+  return value.replace(/\{(\w+)\}/g, (_, k) =>
+    params[k] !== undefined ? String(params[k]) : `{${k}}`,
+  );
+}
+
+// Test-only helper to reset module state between cases.
+export function __resetForTests() {
+  currentLocale = 'en';
+  warnedUnknown = false;
+}

package/src/lib/output.js

@@ -0,0 +1,139 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { formatBanner, formatCompletionSummary } from './ui.js';
+import { t } from './messages/index.js';
+
+// One predicate, six inputs, applied once. See plan §"Decision matrix".
+export function shouldShowBanner(options = {}, runtime = {}, env = process.env, stdout = process.stdout) {
+  if (options.json) return false;
+  if (options.quiet) return false;
+  if (options.nonInteractive) return false;
+  if (runtime.isAgent) return false;
+  if (env.CI) return false;
+  if (!stdout.isTTY) return false;
+  return true;
+}
+
+function noopSpinner() {
+  // Matches the subset of the ora API the CLI calls.
+  const noop = {
+    start() { return noop; },
+    succeed() { return noop; },
+    fail() { return noop; },
+    stop() { return noop; },
+    text: '',
+  };
+  return noop;
+}
+
+export function createOutput(options = {}, runtime = {}, {
+  stdout = process.stdout,
+  stderr = process.stderr,
+  env = process.env,
+} = {}) {
+  const json = !!options.json;
+  const quiet = !!options.quiet || !!runtime.isAgent;
+  const showBanner = shouldShowBanner(options, runtime, env, stdout);
+
+  return {
+    banner() {
+      if (!showBanner) return;
+      stderr.write('\n' + formatBanner() + '\n\n');
+    },
+
+    step(text) {
+      if (json || quiet) return;
+      stderr.write(chalk.green('  ✓') + ` ${text}\n`);
+    },
+
+    info(text) {
+      if (json || quiet) return;
+      stderr.write(`  ${text}\n`);
+    },
+
+    error(text, payload) {
+      if (json) {
+        stderr.write(JSON.stringify({ error: text, ...(payload || {}) }) + '\n');
+        return;
+      }
+      stderr.write(chalk.red(`  ${text}`) + '\n');
+    },
+
+    success(payload) {
+      if (json) {
+        const safe = {
+          skill: payload.skill,
+          source: payload.source,
+          agents: (payload.agents || []).map(a => ({ slug: a.slug, path: a.path })),
+          scope: payload.scope,
+        };
+        if (payload.files !== undefined) safe.files = payload.files;
+        if (payload.duration_ms !== undefined) safe.duration_ms = payload.duration_ms;
+        stdout.write(JSON.stringify(safe) + '\n');
+        return;
+      }
+      if (quiet) {
+        const { skill, agents, scope } = payload;
+        const agentSlugs = (agents || []).map(a => a.slug || a.name).join(',');
+        stdout.write(`installed ${skill} for ${agentSlugs} (${scope})\n`);
+        return;
+      }
+      stderr.write('\n' + formatCompletionSummary({
+        skillName: payload.skill,
+        scope: payload.scope,
+        agents: payload.agents,
+        isGithub: payload.isGithub,
+        namespace: payload.namespace,
+      }) + '\n\n');
+    },
+
+    dryRun(payload) {
+      if (json) {
+        const safe = {
+          dry_run: true,
+          skill: payload.skill,
+          source: payload.source,
+          agents: (payload.agents || []).map(a => ({ slug: a.slug, path: a.path })),
+          scope: payload.scope,
+        };
+        stdout.write(JSON.stringify(safe) + '\n');
+        return;
+      }
+      if (quiet) {
+        const { skill, agents, scope } = payload;
+        const agentSlugs = (agents || []).map(a => a.slug || a.name).join(',');
+        stdout.write(`would install ${skill} for ${agentSlugs} (${scope})\n`);
+        return;
+      }
+      stderr.write('\n' + chalk.yellow(`  ${t('add.dry_run.header')}`) + '\n');
+      const src = payload.source || {};
+      let srcStr;
+      if (src.type === 'github') {
+        srcStr = `${src.owner}/${src.repo}`;
+        if (src.ref) srcStr += `@${src.ref}`;
+        if (src.path) srcStr += ` (${src.path})`;
+      } else {
+        srcStr = src.namespace ? `registry (${src.namespace})` : 'registry';
+      }
+      stderr.write(`  ${t('add.dry_run.source', { source: srcStr })}\n`);
+      stderr.write(`  ${t('add.dry_run.scope', { scope: payload.scope })}\n`);
+      for (const a of payload.agents || []) {
+        stderr.write(`  ${chalk.cyan('•')} ${t('add.dry_run.would_write', { path: a.path })}\n`);
+      }
+      stderr.write('\n');
+    },
+
+    json(obj) {
+      stdout.write(JSON.stringify(obj) + '\n');
+    },
+
+    spinner(text) {
+      if (json || quiet) return noopSpinner();
+      return ora({ text, indent: 2, stream: stderr }).start();
+    },
+
+    showBanner,
+    isQuiet: quiet,
+    isJson: json,
+  };
+}

package/src/lib/parse-source.js

@@ -1,7 +1,117 @@
-export function parseGithubSource(input) {
-  const parts = input.split('/');
-  if (parts.length === 2 && parts[0] && parts[1]) {
-    return { owner: parts[0], repo: parts[1] };
+import { UsageError } from './errors.js';
+
+// `parseSource(input)` returns:
+//   { kind: 'registry', name }                                                 (bare slug)
+//   { kind: 'github', owner, repo, ref?, path?, skill? }                       (any GitHub form)
+// or throws UsageError.
+//
+// Supported GitHub shapes:
+//   owner/repo
+//   owner/repo@skill
+//   owner/repo#ref
+//   owner/repo#ref@skill
+//   https://github.com/owner/repo[.git]
+//   https://github.com/owner/repo/tree/<ref>/<sub/path>
+//
+// SSH (`git@github.com:owner/repo`) and local paths are intentionally rejected
+// for v1 — see the plan's Scope Boundaries.
+
+function rejectTraversal(value, label) {
+  if (!value) return;
+  const segments = value.split(/[\\/]/);
+  if (segments.some(s => s === '..' || s === '.')) {
+    throw new UsageError(`invalid ${label}: path traversal not allowed`);
   }
-  return null;
+}
+
+function parseSlugTail(tail) {
+  // tail looks like "" | "#ref" | "@skill" | "#ref@skill"
+  let ref;
+  let skill;
+  if (tail.startsWith('#')) {
+    const rest = tail.slice(1);
+    const at = rest.indexOf('@');
+    if (at === -1) {
+      ref = rest;
+    } else {
+      ref = rest.slice(0, at);
+      skill = rest.slice(at + 1);
+    }
+    if (ref === '') throw new UsageError('invalid source: empty ref after "#"');
+    if (at !== -1 && skill === '') throw new UsageError('invalid source: empty skill after "@"');
+  } else if (tail.startsWith('@')) {
+    skill = tail.slice(1);
+    if (skill === '') throw new UsageError('invalid source: empty skill after "@"');
+  } else if (tail.length > 0) {
+    throw new UsageError(`invalid source: unexpected suffix "${tail}"`);
+  }
+  return { ref: ref || undefined, skill: skill || undefined };
+}
+
+export function parseSource(input) {
+  if (typeof input !== 'string' || input.trim() === '') {
+    throw new UsageError('empty source: pass a skill name or owner/repo');
+  }
+  const trimmed = input.trim();
+
+  if (trimmed.startsWith('git@')) {
+    throw new UsageError('SSH GitHub URLs not yet supported — use https://github.com/owner/repo');
+  }
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    // `new URL()` silently normalizes ../ out of the path — check the raw
+    // input first so a crafted URL like ".../tree/main/../etc" is rejected.
+    rejectTraversal(trimmed.split('://')[1] || trimmed, 'URL');
+    let url;
+    try { url = new URL(trimmed); }
+    catch { throw new UsageError(`invalid URL: ${trimmed}`); }
+
+    if (url.hostname !== 'github.com' && url.hostname !== 'www.github.com') {
+      throw new UsageError(`only github.com URLs are supported, got ${url.hostname}`);
+    }
+
+    const parts = url.pathname.split('/').filter(Boolean);
+    if (parts.length < 2) throw new UsageError(`URL must include owner/repo: ${trimmed}`);
+    const owner = parts[0];
+    let repo = parts[1].replace(/\.git$/, '');
+
+    const out = { kind: 'github', owner, repo };
+
+    if (parts[2] === 'tree' && parts.length >= 4) {
+      out.ref = parts[3];
+      if (parts.length > 4) {
+        const subPath = parts.slice(4).join('/');
+        rejectTraversal(subPath, 'path');
+        out.path = subPath;
+      }
+    } else if (parts.length > 2) {
+      throw new UsageError(`unsupported URL shape: ${trimmed}`);
+    }
+
+    return out;
+  }
+
+  if (!trimmed.includes('/')) {
+    return { kind: 'registry', name: trimmed };
+  }
+
+  // owner/repo[#ref][@skill]
+  const tailStart = Math.min(
+    trimmed.indexOf('#') === -1 ? Infinity : trimmed.indexOf('#'),
+    trimmed.indexOf('@') === -1 ? Infinity : trimmed.indexOf('@'),
+  );
+  const head = tailStart === Infinity ? trimmed : trimmed.slice(0, tailStart);
+  const tail = tailStart === Infinity ? '' : trimmed.slice(tailStart);
+
+  const parts = head.split('/');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new UsageError(`invalid source: expected owner/repo, got "${input}"`);
+  }
+  rejectTraversal(head, 'source');
+
+  const { ref, skill } = parseSlugTail(tail);
+  const out = { kind: 'github', owner: parts[0], repo: parts[1] };
+  if (ref) out.ref = ref;
+  if (skill) out.skill = skill;
+  return out;
 }

package/src/lib/prompt.js

@@ -1,7 +1,15 @@
 import chalk from 'chalk';
+import { UsageError } from './errors.js';
+import { t } from './messages/index.js';
 
 const orange = chalk.hex('#FF8C00');
 
+function assertTty() {
+  if (!process.stdin.isTTY) {
+    throw new UsageError(t('error.no_tty_no_yes'));
+  }
+}
+
 // --- strip ANSI for width calculation ---
 
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
@@ -19,6 +27,7 @@ function stripAnsi(str) {
  * @returns {Promise<any>} selected value
  */
 export function selectPrompt(question, choices, { defaultIndex = 0 } = {}) {
+  assertTty();
   return new Promise((resolve) => {
     let selected = defaultIndex;
     const { stdin, stdout } = process;
@@ -43,7 +52,7 @@ export function selectPrompt(question, choices, { defaultIndex = 0 } = {}) {
         return `  ${marker} ${label}${hint}`;
       });
       lines.push('');
-      lines.push(chalk.dim('  ↑↓ naviger · enter vælg · esc tilbage'));
+      lines.push(chalk.dim(`  ${t('hints.select')}`));
       return lines;
     }
 
@@ -134,10 +143,10 @@ export function selectPrompt(question, choices, { defaultIndex = 0 } = {}) {
  * @param {{ label: string, value: any }[]} choices
  * @returns {Promise<any[]|null>} array of selected values, or null if Esc
  */
-export function checkboxPrompt(question, choices, { pageSize = 10 } = {}) {
+export function checkboxPrompt(question, choices) {
+  assertTty();
   return new Promise((resolve) => {
     let cursor = 0;
-    let scrollOffset = 0;
     const checked = new Array(choices.length).fill(false);
     const { stdin, stdout } = process;
     const cols = stdout.columns || 80;
@@ -152,22 +161,13 @@ export function checkboxPrompt(question, choices, { pageSize = 10 } = {}) {
     }
 
     function render() {
-      const visible = choices.slice(scrollOffset, scrollOffset + pageSize);
-      const lines = visible.map((c, vi) => {
-        const i = vi + scrollOffset;
+      const lines = choices.map((c, i) => {
         const box = checked[i] ? orange('◼') : '◻';
         const label = i === cursor ? orange(c.label) : c.label;
         return `  ${box} ${label}`;
       });
-      if (scrollOffset > 0) {
-        lines.unshift(chalk.dim(`  ↑ ${scrollOffset} mere`));
-      }
-      const remaining = choices.length - (scrollOffset + pageSize);
-      if (remaining > 0) {
-        lines.push(chalk.dim(`  ↓ ${remaining} mere`));
-      }
       lines.push('');
-      lines.push(chalk.dim('  ↑↓ naviger · space skift · enter bekræft · esc tilbage'));
+      lines.push(chalk.dim(`  ${t('hints.checkbox')}`));
       return lines;
     }
 
@@ -234,20 +234,14 @@ export function checkboxPrompt(question, choices, { pageSize = 10 } = {}) {
       // Up / Left
       else if (key === '\x1b[A' || key === '\x1b[D') {
         cursor = (cursor - 1 + choices.length) % choices.length;
-        if (cursor === choices.length - 1) scrollOffset = Math.max(0, choices.length - pageSize);
       }
       // Down / Right
       else if (key === '\x1b[B' || key === '\x1b[C') {
         cursor = (cursor + 1) % choices.length;
-        if (cursor === 0) scrollOffset = 0;
       } else {
         return;
       }
 
-      // Keep cursor within the visible scroll window
-      if (cursor < scrollOffset) scrollOffset = cursor;
-      if (cursor >= scrollOffset + pageSize) scrollOffset = cursor - pageSize + 1;
-
       // Redraw
       const upCount = totalPhysicalLines(prevLines) - 1;
       if (upCount > 0) stdout.write(`\x1b[${upCount}A`);

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

@@ -0,0 +1,141 @@
+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
+// Returns the matched directory path, or null if no match.
+//
+// Ported from the agentskills website's `matchSkillToPath` so behavior stays
+// in sync between registry indexing and CLI installs.
+export function matchSkillDir(requested, owner, candidates) {
+  if (candidates.length === 0) return null;
+
+  const wantLower = requested.toLowerCase();
+
+  // 1. Exact directory match (the last path segment).
+  const exact = candidates.find(p => {
+    const last = p.split('/').pop();
+    return last === requested || last.toLowerCase() === wantLower;
+  });
+  if (exact) return exact;
+
+  // 2. Same-path match (user passed the full path already).
+  const fullMatch = candidates.find(p => p === requested || p.toLowerCase() === wantLower);
+  if (fullMatch) return fullMatch;
+
+  // 3. Strip common owner-style prefixes.
+  const prefixes = [`${owner}-`, `${owner.toLowerCase()}-`, 'vercel-', 'anthropic-', 'claude-'];
+  let stripped = requested;
+  for (const pre of prefixes) {
+    if (wantLower.startsWith(pre.toLowerCase())) {
+      stripped = requested.slice(pre.length);
+      break;
+    }
+  }
+  if (stripped !== requested) {
+    const m = candidates.find(p => {
+      const last = p.split('/').pop().toLowerCase();
+      return last === stripped.toLowerCase();
+    });
+    if (m) return m;
+  }
+
+  // 4. Fuzzy: collapse to alphanumerics, lowercase, then compare.
+  const normalize = s => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const wantNorm = normalize(requested);
+  const fuzzy = candidates.find(p => normalize(p.split('/').pop()) === wantNorm);
+  if (fuzzy) return fuzzy;
+
+  // 5. Single-skill fallback.
+  if (candidates.length === 1) return candidates[0];
+
+  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 };
+}