| name | sync-agent-symlinks |
| description | Analyze and synchronize agent skill exposure after ai-specs skill changes (additions, removals, renames). Use when skills are added/removed in ai-specs and .claude/skills and .cursor/skills must stay aligned through symlinks. |
| author | LIDR.co |
| version | 1.0.0 |
sync-agent-symlinks Skill
Keep agent-facing skill structures synchronized with ai-specs/skills as the canonical source.
Use this skill after any change in ai-specs/skills (new skill, removed skill, renamed skill, moved skill), especially when you need to avoid stale or broken symlinks.
Scope and Safety Rules
- Canonical source is
ai-specs/skills.
- Mirror targets are:
.claude/skills.cursor/skills
- Manage only entries that are symlinks to
../../ai-specs/skills/<skill-name>.
- Do not delete non-symlink directories in mirror targets unless the user explicitly asks.
- Never overwrite a real directory automatically; report it as a conflict.
Workflow
Step 1 - Build inventories
Collect three inventories:
- Canonical skills from
ai-specs/skills/*/SKILL.md
- Mirror entries in
.claude/skills
- Mirror entries in
.cursor/skills
From mirror entries, classify:
linked: valid symlink pointing to existing canonical skillbroken: symlink target missingorphan: symlink points to canonical namespace but skill no longer existsconflict: non-symlink entry with same name as canonical skillexternal: entry not managed by canonical symlink policy (leave unchanged)
Step 2 - Compute sync plan
For each mirror target:
to_add: canonical skills missing in mirror targetto_fix: broken canonical symlinks that should be recreatedto_remove: orphan canonical symlinks with no canonical sourceto_skip: conflicts and external entries (report only)
Step 3 - Apply sync safely
Apply changes in this order:
- Add missing symlinks:
<mirror>/<skill-name> -> ../../ai-specs/skills/<skill-name>
- Fix broken canonical symlinks:
- Remove broken link and recreate the same canonical link
- Remove orphan canonical symlinks:
- Remove symlink only if it points to canonical namespace and skill is gone
Never remove:
- non-symlink directories
- files not under canonical symlink policy
Step 4 - Verify integrity
After changes:
- Confirm every canonical skill exists in both mirrors as a valid symlink, or is explicitly listed as conflict.
- Confirm no broken canonical symlinks remain.
- Confirm external entries remain untouched.
Step 5 - Report results
Return a concise sync report:
- Canonical skills count
- Per mirror target:
- added
- fixed
- removed
- conflicts
- skipped external entries
- Remaining blockers (if any)
Add/Remove Scenarios
Scenario A - New skill added in ai-specs
Expected behavior:
- Add missing symlink in
.claude/skills
- Add missing symlink in
.cursor/skills
- Verify both links resolve to canonical folder
Scenario B - Skill removed from ai-specs
Expected behavior:
- Remove orphan canonical symlink from
.claude/skills
- Remove orphan canonical symlink from
.cursor/skills
- Keep non-canonical directories untouched and report them
Command Patterns (Reference)
Use equivalent commands for your environment:
ls ai-specs/skills
ls -la .claude/skills
ls -la .cursor/skills
ln -s ../../ai-specs/skills/<skill-name> .claude/skills/<skill-name>
ln -s ../../ai-specs/skills/<skill-name> .cursor/skills/<skill-name>
rm .claude/skills/<skill-name>
rm .cursor/skills/<skill-name>
Red Flags
Never:
- treat
ai-specs as non-canonical
- auto-delete real directories in mirror targets
- leave broken canonical symlinks after sync
- silently skip conflicts without reporting
Always:
- analyze before changing
- apply minimal safe changes
- preserve non-canonical entries
- provide a final sync report with blockers
