Function findSkillRoot

src/skills/installer.ts:120–158

Walk a freshly extracted source looking for a SKILL.md root.

(src: string)

/** Walk a freshly extracted source looking for a SKILL.md root. */
async function findSkillRoot(src: string): Promise<string> {
  // Track the last non-ENOENT stat failure so a real IO error (e.g. EACCES on a
  // candidate path) isn't masked behind a generic "couldn't find SKILL.md".
  let lastStatErr: any;
  const tryStat = async (p: string): Promise<boolean> => {
    try {
      await fs.stat(p);
      return true;
    } catch (e: any) {
      if (e?.code !== 'ENOENT') lastStatErr = e;
      return false;
    }
  };

  // Direct hit: src/SKILL.md
  if (await tryStat(path.join(src, 'SKILL.md'))) return src;

  // Single child wrapper (common with tar extracts and git clones)
  const entries = await fs.readdir(src, { withFileTypes: true });
  const dirs = entries.filter(e => e.isDirectory() && !e.name.startsWith('.'));
  if (dirs.length === 1) {
    const inner = path.join(src, dirs[0]!.name);
    if (await tryStat(path.join(inner, 'SKILL.md'))) return inner;
  }

  // skills/<name>/SKILL.md layout (multi-skill repos pick the first)
  const skillsParent = path.join(src, 'skills');
  try {
    const sub = await fs.readdir(skillsParent, { withFileTypes: true });
    for (const ent of sub) {
      if (!ent.isDirectory()) continue;
      const cand = path.join(skillsParent, ent.name);
      if (await tryStat(path.join(cand, 'SKILL.md'))) return cand;
    }
  } catch {}

  const ioNote = lastStatErr ? ` (note: a filesystem error occurred while looking: ${lastStatErr?.message ?? lastStatErr})` : '';
  throw new Error(`Couldn't find a SKILL.md in ${src}. Skills must ship a top-level SKILL.md or skills/<name>/SKILL.md.${ioNote}`);
}

async function copyInto(srcRoot: string, originalSource: string, opts: { force?: boolean }): Promise<InstallResult> {
  const raw = await fs.readFile(path.join(srcRoot, 'SKILL.md'), 'utf-8');