[dacharyc]

Fixes #77.

What was wrong

DetectSkills looked only at the immediate subdirectories of the given path. A catalog laid out as skills/<product>/<skill>/ (the NVIDIA layout from the issue) reported "no skills found" and had to be validated one product directory at a time. The agentskills.io client implementation guide tells scanners to walk 4-6 levels and stop at 2000 directories.

What changed

• skillcheck.DiscoverSkills(root, maxDepth) searches breadth-first to a depth bound (default 6, skillcheck.DefaultMaxDepth) and returns a Discovery: the mode, the sorted skill directories, each one's depth below the root, and a Truncated flag set when the scan hit the 2000-listing budget. DetectSkills keeps its signature and calls it with the default depth, so library callers are unaffected.
• Symlinks are still followed. A skills directory assembled from links to skill folders kept elsewhere is a supported layout, and the existing test for it stands. Each real directory is visited once, keyed by its resolved path, so cycles (loop -> ., up -> ..) and aliases neither loop nor report a skill twice. Per-skill containment in util.SafeReadFile is unchanged.
• The budget cannot be starved. A skill is detected the moment its parent directory is listed, and the budget counts listings, so a wide or linked sibling tree (a link to a 2500-directory tree sorted before the real skill) no longer hides it. A plain breadth-first walk was not enough for this on its own.
• A skill's own subtree is not searched, so a SKILL.md inside a skill's examples or references is not a second skill. Hidden directories, node_modules, and __pycache__ are skipped. .gitignore is not consulted; the budget already bounds the cost of scanning build output.
• CLI: a persistent --max-depth flag on every command (0 searches the given path only, 1 is the previous behavior), a stderr warning when the budget was hit, and the depth named in the "no skills found" error.
• README documents the discovery rules and states that only the given path is searched: the guide's home-directory and .agents/skills scanning is an agent's session-start concern, not a validator's.

The Depths field is there so a later platform-compatibility check can say that a skill found at depth 2 will not be listed by a harness that reads direct children only.

Verification

Tests cover the two-level layout, mixed depths, the depth boundary on both sides, no descent into a skill, hidden and dependency directories, budget truncation, cycle to root, cycle to parent, alias dedupe, a link to a skill outside the root, broken and file links, and the starvation case. A CLI test exercises --max-depth end to end. Symlink tests skip on Windows as the existing ones do.

Against fixtures with a self-loop, a parent loop, a link to a 2500-directory tree, and a link to /, the build reports each skill once, keeps the skill behind the big link, and finishes the link-to-root case in under a second.

go test -race ./... and golangci-lint run are clean.

No CHANGELOG entry, following the release-commit pattern.

[Copilot]

🟡 Changes recommended

Relative library roots can cause symlink aliases to report the same skill twice.

1 open finding

• Normalize relative paths to deduplicate symlinked skills · New

What changed in this PR

Adds bounded discovery of skills under grouping directories, addressing #77 while preserving the DetectSkills API.

Changes:

• Adds breadth-first discovery with depth limits, a listing budget, and symlink deduplication.
• Exposes --max-depth and truncation warnings through the CLI.
• Documents discovery rules and adds regression coverage.

File	Description
skillcheck/​validator.go	Implements bounded nested skill discovery.
skillcheck/​validator_test.go	Covers depth, exclusions, budgets, and symlinks.
README.md	Documents discovery behavior and limits.
cmd/​root.go	Adds depth configuration and discovery diagnostics.
cmd/​exitcode_integration_test.go	Tests CLI depth handling and errors.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.