Support deeper nested skill directory structures (per implementation guide 4-6 depth bound)

[dacharyc]

Background

The agentskills.io specification is ambiguous on nested skill directory layouts, but the implementation guide explicitly states:

Set reasonable bounds (e.g., max depth of 4-6 levels, max 2000 directories) to prevent runaway scanning in large directory trees.

This implies compliant scanners should walk 4-6 directory levels looking for SKILL.md files.

Current behavior

skill-validator check <path> currently expects one of:

• SKILL.md at the given directory, or
• Subdirectories at the immediate level containing SKILL.md

When pointed at a directory that contains product / team subdirectories whose children contain skills (i.e., 2 levels deep), it errors with:

no skills found in <path> (expected SKILL.md or subdirectories containing SKILL.md)

Real-world example: NVIDIA verified skills catalog

NVIDIA's verified Agent Skills catalog uses a 2-level layout:

skills/
├── Megatron-Bridge/
│   ├── update-golden-values/SKILL.md
│   ├── bump-base-image/SKILL.md
│   └── ... (29 skills total)
├── cuopt/
│   ├── cuopt-developer/SKILL.md
│   └── ... (12 skills total)
├── TensorRT-LLM/ ... (25 skills)
└── ... (17 products, 155 SKILL.md files total)

To audit the whole catalog today, the user has to run skill-validator once per product directory and aggregate per-product JSON outputs. A recursive walk to the implementation guide's depth bound would let skill-validator check skills/ cover the entire catalog in one invocation.

Proposed change

1. When the path argument doesn't contain SKILL.md and no immediate subdir contains SKILL.md, walk deeper up to a configurable depth bound. Default 4-6 levels, aligned with the implementation guide.
2. Add --max-depth flag for explicit control.
3. Detect circular symlinks and respect the implementation guide's max 2000 directories recommendation.

Related community discussion

• agentskills/agentskills#137 (open) — clarify whether nested skills are allowed (focused on runtime cross-skill invocation, but adjacent)
• agentskills/agentskills#376 (closed) — direct question about nested directory layouts
• agentskills/agentskills#143 (closed) — proposal for domain-grouped subdirectories
• agentskills/agentskills#59 (open) — proposal for subdirectories in skills

The implementation guide's explicit 4-6 depth bound gives skill-validator a defensible, spec-aligned default.