[DOCS] Symlinked skill directories under ~/.claude/skills/ work — please document the support level (cf. #41451)

Documentation Type

Missing information

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

Where skills live / personal skills

Current Documentation

The skills doc describes personal skills at ~/.claude/skills/<name>/SKILL.md but does not mention whether symlinks are supported.

What's Wrong or Missing?

A personal skill installed as a symlinked directory works end-to-end on macOS, but this is undocumented, so users cannot tell whether it is supported behavior or incidental:

~/.claude/skills/my-skill -> /path/to/git-repo/skill/my-skill

Verified on CLI 2.1.53 and 2.1.177, and on the desktop-app harness 2.1.170 (macOS 14.7.4):

• the skill is discovered at session start and listed as available
• it is auto-invoked from the frontmatter description on a natural-language prompt (confirmed via the Skill tool call in the transcript)
• the /my-skill slash command works

#41451 (symlinked .claude/commands/ not discovered on Linux) suggests symlink discovery has been platform/feature-dependent in the past, which is why an explicit statement would help.

Suggested Improvement

Add a note to "Where skills live" stating whether symlinked skill directories (and symlinked SKILL.md files) are supported, and on which platforms. A one-line note would let git-managed setups rely on it.

Impact

Users who manage skills in a dotfiles/git repo and symlink them into ~/.claude/skills/ (for version control + multi-machine sync) currently rely on undocumented behavior that could regress silently.

Additional Context

Happy to re-test on other platforms/versions if useful.