[FEATURE] Recursive skill discovery - scan subdirectories in ~/.claude/skills/

[simfor99]

Summary

Currently, Claude Code only scans the top-level of ~/.claude/skills/ for skill directories containing SKILL.md files. Skills organized in subdirectories (e.g., ~/.claude/skills/spec-system/spec-creator/) are not discovered automatically.

Problem

When organizing related skills into logical groupings (suites), users must manually create symlinks at the top level for each nested skill:

~/.claude/skills/
├── spec-system/                    ← Container directory
│   ├── spec-creator/SKILL.md       ← Not discovered!
│   ├── spec-executor/SKILL.md      ← Not discovered!
│   └── spec-archiver/SKILL.md      ← Not discovered!
├── spec-creator → spec-system/spec-creator    ← Manual symlink required
├── spec-executor → spec-system/spec-executor  ← Manual symlink required
└── spec-archiver → spec-system/spec-archiver  ← Manual symlink required

Without symlinks, calling Skill("spec-creator") fails with "Unknown skill".

Proposed Solution

Recursively scan ~/.claude/skills/ (and .claude/skills/) for directories containing SKILL.md files, regardless of nesting depth.

Option A: Full Recursive Scan

Scan all subdirectories up to a reasonable depth (e.g., 3 levels).

Option B: Configurable Depth

Add a setting like skills.scanDepth: 2 to control how deep to scan.

Option C: Explicit Suite Marker

Only recurse into directories containing a marker file (e.g., SKILL_SUITE.md or .skill-suite).

Benefits

1. Better organization - Group related skills (spec-system, gsd-toolkit, etc.)
2. No manual symlink maintenance - Skills just work when placed in subdirectories
3. Cleaner top-level - Reduce clutter in ~/.claude/skills/
4. Suite versioning - Version control entire skill suites as units

Current Workaround

Users must:

1. Create symlinks manually: ln -s spec-system/spec-creator spec-creator
2. Maintain a validation script to check for missing symlinks
3. Remember to create symlinks when adding new nested skills

Environment

• Claude Code version: Latest (Jan 2026)
• Platform: All (Linux, macOS, Windows)
• Skills location: ~/.claude/skills/

Related

This is separate from the "nested skills" issues about skills calling other skills (#17351, #17339) - this is purely about directory structure and discovery.

[eins78]

+1 for this feature. We have a specific use case that makes subdirectory support particularly valuable: Team-wide shared config via symlinks

We maintain a company config repo with shared skills, commands, and rules. Each developer symlinks it into their ~/.claude/:

ln -sfn /path/to/config-repo/skills ~/.claude/skills/acme

Inconsistency with commands: This pattern works perfectly for commands—~/.claude/commands/acme/init-agent.md becomes /acme:init-agent. But skills in ~/.claude/skills/acme/my-skill/SKILL.md aren't discovered.

Our workaround: We now iterate and create individual symlinks with a prefix:

for skill_dir in "$repo/skills"/*/; do
ln -sfn "$skill_dir" ~/.claude/skills/acme-"$(basename "$skill_dir")"
done

Recursive discovery (Option A) would let us use a single symlink like we do for commands.

[wolffiex]

Fix is coming in 2.1.10 today

[andrewreedy]

@wolffiex it doesn't look like this is working still. #10238 (comment) -- These issues could likely be merged

[yordis]

I just checked, I can confirm it does not work

[RonanCodes]

Workaround for skill collections:

Until recursive discovery is implemented, here's a script to symlink all skills from a cloned repo:

#!/bin/bash
# sync-skills.sh - Symlink all skills from a collection
REPO_DIR="$1"
TARGET="${2:-$HOME/.claude/skills}"

for skill in "$REPO_DIR"/*/; do
  if [ -f "$skill/SKILL.md" ]; then
    ln -sf "$skill" "$TARGET/"
    echo "✓ $(basename $skill)"
  fi
done

Usage: ./sync-skills.sh ~/my-skills-repo

This lets you git pull to update and re-run the script for new skills. Not ideal, but works.

+1 for native recursive discovery!

[RealmX1]

would be even better if we can have dynamic loading of skills upon start working on subdirectories.

[ThePlenkov]

Strange , version 2.1.6 changelog already declares that it should be enabled - but even i 2.1.45 i still see no efffect