Canonical store (single source of truth): %USERPROFILE%\.cursor\skills
WSL and .agents\skills only link/junction into that folder — never keep a second real copy.
When the user says things like
- "Sync skills" "Sync the skills"
- 「restore / relink WSL skills」
- "Align the Windows and WSL skill directories"
- Just added or removed a skill on one side, want the other side to be consistent immediately
→ Run the full sync workflow below. Do not improvise a copy/rsync of the whole tree unless the scripts fail.
Full sync workflow (default)
Run from Windows (PowerShell / Cursor on Windows). Execute both steps in order.
0) Resolve this skill’s install path
npx skills add may place the skill under .agents\skills or .cursor\skills. Resolve once, then reuse:
$SkillRoot = @(
"$env:USERPROFILE\.cursor\skills\sync-skills-wsl",
"$env:USERPROFILE\.agents\skills\sync-skills-wsl"
) | Where-Object { Test-Path "$_\scripts\restore-windows.ps1" } | Select-Object -First 1
if (-not $SkillRoot) { throw "sync-skills-wsl not found under .cursor\skills or .agents\skills" }
1) Windows junctions
powershell -NoProfile -ExecutionPolicy Bypass -File "$SkillRoot\scripts\restore-windows.ps1"
What it does:
- Ensures
%USERPROFILE%\.agents\skillsexists - For each real folder under
.agents\skills(not already a junction): copy into.cursor\skillsif missing, then replace the agents entry with a junction →.cursor\skills\<name> - Skips entries that are already junctions/symlinks
- Removes broken junctions whose target no longer exists
2) WSL symlinks
$drive = $SkillRoot.Substring(0, 1).ToLower()
$unix = ($SkillRoot -replace '\\', '/') -replace '^[A-Za-z]:', "/mnt/$drive"
wsl -e bash -lc "$unix/scripts/restore-wsl.sh"
If USERNAME / profile folder name mismatches, set WIN_USER inside WSL or pass it when calling the script.
What it does:
~/.cursor/skills→/mnt/c/Users/<win>/.cursor/skills~/.agents→/mnt/c/Users/<win>/.agents~/.claude→/mnt/c/Users/<win>/.claude(only if that Windows dir exists)- Existing different targets: back up to
*.bak.<timestamp>then relink - Then runs
absorb-agents-skills.sh(same absorb/junction logic from inside WSL)
3) Report to the user
After both steps, briefly confirm:
- Canonical path and skill count (dirs under
.cursor\skills, excluding.gitand this skill’s non-skill noise if any — count skill folders that containSKILL.md) - WSL link targets (
readlink/ “Already linked”) - Any broken junctions removed or absorb actions
Partial runs
| User intent | Run |
|---|---|
Only fix Windows .agents junctions |
Step 1 only |
| Only fix WSL links | Step 2 only |
| Just deleted skills, clean dangling links | Step 1 (broken-junction cleanup) + Step 2 |
Model (mental picture)
Windows: %USERPROFILE%\.cursor\skills ← canonical content
%USERPROFILE%\.agents\skills\* ← junctions → cursor\skills\*
WSL: ~/.cursor/skills → /mnt/c/Users/<win>/.cursor/skills
~/.agents → /mnt/c/Users/<win>/.agents
~/.claude → /mnt/c/Users/<win>/.claude (optional)
Do / Don’t
- Do treat
.cursor\skillsas the only place to add/edit skill files - Do re-run this sync after installing skills into
.agents\skillsor deleting skills from.cursor\skills - Don’t
cp -ra full second tree into WSL home - Don’t create skills under
~/.cursor/skills-cursor/(Cursor built-ins) - Don’t leave real duplicates in both
.agents\skillsand.cursor\skills
Legacy scripts
Older copies may still exist at:
~/.cursor/skills/restore-skills.ps1~/.cursor/skills/restore-skills.sh~/.cursor/skills/absorb-agents-skills.sh
Prefer this skill’s scripts/ (portable paths). If legacy scripts are present and user asks to run "that ps1", either is fine; then still run the WSL step.
Troubleshooting
| Symptom | Fix |
|---|---|
wsl not found / fails |
User must enable WSL; stop and report |
Missing /mnt/c/Users/<win>/.cursor/skills |
Confirm Windows path; fix WIN_USER in env or script args |
WSL home is not /root |
restore-wsl.sh uses $HOME — run inside the intended distro (wsl -d <name> ... if needed) |
| Junction create fails | Run PowerShell outside a restricted sandbox; need filesystem permission on %USERPROFILE% |
| Skill count mismatch Win vs WSL | Re-run full sync; verify WSL path is a symlink to /mnt/c/..., not a real dir |
Scripts
| Script | Role |
|---|---|
| scripts/restore-windows.ps1 | Absorb + junctions + broken cleanup |
| scripts/restore-wsl.sh | WSL symlinks + absorb |
| scripts/absorb-agents-skills.sh | WSL-side absorb via powershell.exe junctions |