Skills in ~/.claude/skills/ via directory junctions not resolved at session start (Windows)
Bug Description
Skills installed in ~/.claude/skills/ via Windows directory junctions (mklink /J) are not resolved during initial skill discovery at session start. The skills appear in the system reminder skill list (proving discovery occurred), but invoking them via /skill-name fails with "Unknown skill" or "not a prompt-based skill" errors.
After running unrelated tool calls mid-session, the same skills invoke successfully — suggesting the execution layer resolves junctions correctly but the initial validation/discovery scan does not.
Environment
- OS: Windows 11 Pro 10.0.26200
- Shell: PowerShell / cmd (Git Bash used for verification)
- Claude Code: Latest (via CLI)
- Junction type: Windows directory junction (
mklink /J), confirmed via PowerShellGet-ItemshowingLinkType: Junction
Reproduction Steps
- Create skills in a development repo with the standard
<skill-name>/SKILL.mdstructure - Create directory junctions from
~/.claude/skills/<skill-name>→<dev-repo>/<skill-name>/ - Start a new Claude Code session (or run
/clear) - Immediately try to invoke one of the junctioned skills via
/skill-name - Result: Skill fails to resolve ("Unknown skill" or "not a prompt-based skill")
- Run any other tool call (Read, Bash, etc.)
- Try invoking the same skill again
- Result: Skill now works correctly
Expected Behavior
Skills in ~/.claude/skills/ should resolve immediately at session start regardless of whether the directory is a real directory or a junction/symlink.
Verification
PowerShell confirms the junctions are valid:
PS> Get-Item C:\Users\gotsa\.claude\skills\checkpoint | Select Name, Attributes, LinkType, Target
Name Attributes LinkType Target
---- ---------- -------- ------
checkpoint Directory, ReparsePoint Junction {C:\Users\gotsa\source\repos\checkpoint-skill\checkpoint}
The SKILL.md files are accessible through the junction:
$ test -f ~/.claude/skills/checkpoint/SKILL.md && echo "EXISTS" || echo "NOT FOUND"
EXISTS
The skills appear in the system reminder skill listing at conversation start, confirming partial discovery occurs.
Impact
This breaks the intended development workflow for skill authors who maintain skills in a separate repo and junction them into ~/.claude/skills/ for global availability. The ~/.claude/skills/ directory is the documented location for user-scoped global skills, and junctions are the standard Windows mechanism for this pattern (no admin privileges required, unlike symlinks).
Workaround
Running any tool call before invoking the skill forces the registry to refresh and resolves the issue for the remainder of the session. This is not practical for normal usage.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗