What does this PR do?

Fixes recursive skill discovery for skill directories that are symlinked under ~/.hermes/skills/<category>/<name> or configured external skill roots.

Direct path loading already worked for some top-level symlinks, but recursive discovery used Path.rglob() / os.walk() without following directory links. That made skills_list, bare-name skill_view, and the skills system prompt disagree about whether the same skill existed. This change centralizes recursive skill-file discovery on a symlink-aware, cycle-safe iterator.

Related Issue

Fixes #8293

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Updated agent/skill_utils.py so iter_skill_index_files() follows symlinked directories while visiting each real directory only once.
• Switched tools/skills_tool.py recursive SKILL.md scans to the shared iterator for _find_all_skills(), skills_categories(), and bare-name skill_view() fallback.
• Added regression tests for nested symlinked skills in skills_list, skill_view, and build_skills_system_prompt().
• Added cycle-protection coverage for recursive symlink loops.

How to Test

1. Run:

   python -m pytest tests/tools/test_skills_tool.py tests/agent/test_prompt_builder.py -q -o addopts=''

2. Confirm nested symlinked skill directories appear in skills_list().
3. Confirm skill_view("<name>") can load a symlinked skill by bare directory name.
4. Confirm the prompt-builder skills index includes the same symlinked skill.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu Linux 6.8 x86_64

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

N/A

Screenshots / Logs

Targeted test output:

192 passed, 1 warning in 1.42s