Function walkSkillDir

packages/agent-core/src/skill/scanner.ts:143–251

(
    dirPath: string,
    root: SkillRoot,
    isTopLevel: boolean,
    depth: number,
    subSkillParentName?: string,
  )

  const byName = new Map<string, SkillDefinition>();

  async function walkSkillDir(
    dirPath: string,
    root: SkillRoot,
    isTopLevel: boolean,
    depth: number,
    subSkillParentName?: string,
  ): Promise<void> {
    if (depth > MAX_SKILL_SCAN_DEPTH) return;

    let entries: readonly string[];
    try {
      // Sorted so first-wins collision resolution across sibling directories
      // is deterministic rather than dependent on filesystem readdir order.
      entries = [...(await readdir(dirPath))].toSorted();
    } catch (error) {
      warn(`Failed to read skill directory ${dirPath}`, error);
      return;
    }

    const directorySkills = new Set<string>();
    const subdirs: string[] = [];
    for (const entry of entries) {
      const entryPath = path.join(dirPath, entry);
      // A directory holding SKILL.md is a skill bundle: register it, then keep
      // descending so nested SKILL.md bundles remain discoverable as sub-skills.
      if (await isFile(path.join(entryPath, 'SKILL.md'))) {
        directorySkills.add(entry);
      }
      if (entry === 'node_modules' || entry.startsWith('.')) continue;
      if (await isDir(entryPath)) subdirs.push(entry);
    }

    const allowedSubSkillBundles = new Map<string, string>();
    for (const entry of directorySkills) {
      const skill = await parseAndRegister({
        parse,
        byName,
        skillMdPath: path.join(dirPath, entry, 'SKILL.md'),
        skillDirName: entry,
        root,
        onDiscoveredSkill: options.onDiscoveredSkill,
        warn,
        skip,
        subSkillParentName,
      });
      if (skill !== undefined && hasSubSkillEnabled(skill)) {
        allowedSubSkillBundles.set(entry, skill.name);
      }
    }

    // Flat .md skills count only at a root's top level; deeper .md files are
    // skill payload (e.g. references/foo.md), not skills.
    if (isTopLevel) {
      // A SKILL.md placed directly at a plugin skill root (e.g. plugin root fallback)
      // is treated as a single skill bundle. This only applies to plugin-derived roots,
      // not to user/project skill directories.
      if (root.plugin !== undefined) {
        const rootSkillMd = path.join(dirPath, 'SKILL.md');