User-level skills not loaded when ~/.claude/skills is a symlink (regression since ~v2.1.69)
Description
User-level skills defined in ~/.claude/skills/ are no longer discovered/loaded when that directory is a symlink. This was working in earlier versions and appears to be a regression likely introduced around v2.1.69 (which included symlink-related security fixes).
Current version
Claude Code 2.1.81
Setup
~/.claude/skills is a symlink to ~/dotfiles/.claude/skills/ (a common pattern for dotfiles management). The target directory contains multiple valid skills, each with a proper SKILL.md:
~/.claude/skills -> ~/dotfiles/.claude/skills/
├── beam-introspection/SKILL.md
├── liveview-debugger/SKILL.md
├── mjml/SKILL.md
├── oracle/SKILL.md
├── psu/SKILL.md
└── ...Expected behavior
User-level skills from ~/.claude/skills/ should be discovered and appear in /skills, regardless of whether the directory is a symlink. This is how it worked before.
Actual behavior
- Project-level skills (from
.claude/skills/inside the repo, which is a real directory) load correctly. - User-level skills from the symlinked
~/.claude/skills/are completely missing from the skills list.
Likely cause
v2.1.69 changelog mentions:
Fixed symlink bypass where writing new files through a symlinked parent directory could escape the working directory
This security fix likely changed how symlinks are resolved during skills discovery, causing user-level symlinked skill directories to be skipped entirely.
Workaround
Replacing the symlink with a real directory and symlinking individual skill subdirectories inside it may work, but defeats the purpose of symlinking the entire skills directory for dotfiles management.
Notes
- Symlinks for rules are explicitly documented as supported ("Share rules across projects with symlinks")
- The same pattern should work for skills
4 Comments
Update: Replacing the top-level symlink with a real directory containing individual symlinks to each skill subdirectory also does NOT work. Claude Code appears to skip symlinks at every level during user-level skills discovery.
Testing with fully copied (non-symlinked) directories next to confirm the issue is specifically symlink-related.
Closing — the issue is not symlink-related. Even with fully copied (non-symlinked) real directories under ~/.claude/skills/, user-level skills are still not loaded. The root cause is elsewhere in user-level skills discovery.
Found 2 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.