Create, audit, repair, and document cross-platform symlinks that work correctly on both Windows and macOS/Linux. Use this skill whenever the user mentions symlinks, symbolic links, junction points, .gitconfig symlinks, broken links after git pull, cross-platform path issues, or needs help with ln -s equivalents on Windows. Also trigger when the user reports that files are missing or wrong after switching between Mac and Windows machines using Git. This skill solves the common problem where symlinks committed on macOS show up as plain text files on Windows (and vice versa) because of Git's core.symlinks setting or missing Developer Mode / elevated permissions.
From link-checkernpx claudepluginhub richfrem/agent-plugins-skills --plugin link-checkerThis skill uses the workspace's default tool permissions.
evals/evals.jsonevals/results.tsvreferences/troubleshooting.mdscripts/symlink_manager.pyExecutes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Guides root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Git symlinks break across platforms because:
| Issue | macOS/Linux | Windows |
|---|---|---|
| Git setting | core.symlinks=true (default) | core.symlinks=false (default, unless Dev Mode enabled) |
| Link type | ln -s symlink | NTFS symlink or Junction Point |
| Permissions | Any user | Requires Developer Mode or admin elevation |
| Git behaviour | Stores as symlink object | Stores as plain text file containing the target path |
When core.symlinks=false, Git checks out a symlink as a plain text file whose contents are the target path. When you then git pull on the other machine, that text file arrives instead of a real link — silent, no error.
Run the diagnosis script first. It checks:
git config core.symlinks (local + global)python ./scripts/symlink_manager.py diagnose
On Windows (needs Developer Mode enabled first, or run as admin):
git config core.symlinks true
git rm --cached -r . # unstage everything
git reset --hard # re-checkout with symlinks honoured
On macOS / Linux (usually already correct):
git config --get core.symlinks # should say "true"
Add a .gitattributes line to lock symlinks in the repo:
* text=auto
*.symlink -text
Always use scripts/symlink_manager.py rather than raw os.symlink() because it:
symlinks.json manifest so links can be re-created after a git reset --hard# Create a single symlink
python ./scripts/symlink_manager.py create --src configs/shared.cfg --dst app/shared.cfg
# Re-create ALL links from the manifest
python ./scripts/symlink_manager.py restore
# Audit: list broken or missing links
python ./scripts/symlink_manager.py audit
# Full diagnosis of the environment
python ./scripts/symlink_manager.py diagnose
Commit symlinks.json to the repo. On a fresh checkout (or after a git pull breaks links on Windows), any developer runs:
python ./scripts/symlink_manager.py restore
…and all links are recreated correctly for their platform.
git config --global core.symlinks true after enabling Developer Mode.core.symlinks=false inherited from a shared config.git config --list --show-origin | grep symlinks to see where the setting comes from.references/troubleshooting.md — Common error messages and fixesscripts/symlink_manager.py — The cross-platform Python scriptRead references/troubleshooting.md when the user reports specific error messages.