Sync Skills

Sync Skills Between Repo and Global Locations

Link or copy skills between this repo and the global skill directories that Claude Code and Cursor read from. Symlinks are the default — edits in the repo are instantly available everywhere without copying.

Skill Locations

The repo organizes skills into category directories (contracts/, meta/, roles/, workflows/, orchestrator/, git/). For Claude Code, symlinks are flattened — each individual skill is linked directly under ~/.claude/skills/ (no category subdirs) because Claude Code only discovers skills at ~/.claude/skills/<skill-name>/SKILL.md. For Cursor, symlinks are created at the category level.

Excluded directories

Two top-level directories under skills/ are excluded from discovery and never get symlinked:

• skills/archive/ — retired skills kept as reference-only audit trail
• skills/in-progress/ — drafts under active development

The exclusion list lives in SKIP_CATEGORIES near the top of scripts/sync-skills.sh. Add a new entry there if another staging directory ever gets introduced. The corresponding paths must also be kept out of .claude-plugin/plugin.json's skills array — otherwise the plugin would load them even though sync-skills doesn't.

Quick Reference

SCRIPT="skills/workflows/sync-skills/scripts/sync-skills.sh"

# Link all repo skill categories to both Claude Code and Cursor
$SCRIPT --link --to-all

# Check what's linked, copied, or missing
$SCRIPT --status

# Remove broken symlinks (e.g. after deleting a skill from the repo)
$SCRIPT --clean

# Link just one category to Claude Code
$SCRIPT --link --to-claude meta

# Copy instead of link (for machines without repo access)
$SCRIPT --copy --to-all

# Remove symlinks (restore independence)
$SCRIPT --unlink --to-all

# Pull a skill from Cursor into the repo
$SCRIPT --from-cursor shell

# Preview what would happen
$SCRIPT --dry-run --link --to-all

Modes

Link Mode (default for --to-*)

Creates symlinks from global locations pointing to repo directories. This is the development workflow — edit skills in the repo and they're instantly live in Claude Code and Cursor.

• Claude Code: Skills are flattened — each individual skill gets its own symlink directly under ~/.claude/skills/ (e.g., ~/.claude/skills/skill-review → repo/skills/meta/skill-review). This is required because Claude Code only discovers skills at ~/.claude/skills/<skill-name>/SKILL.md.
• Cursor: Symlinks are created at the category level (e.g., ~/.cursor/skills-cursor/meta → repo/skills/meta)
• Non-repo skills in global locations (e.g., ~/.claude/skills/builtWithAgent/) are untouched
• If a copy already exists where a symlink would go, the script reports it and replaces the copy with a symlink (use --dry-run to preview first)

Copy Mode (--copy)

Copies skill directories instead of symlinking. Use this when:

• Deploying skills to a machine that doesn't have the repo cloned
• You need a frozen snapshot that won't change with repo edits
• The target location is on a different filesystem that doesn't support symlinks

Pull Mode (--from-cursor, --from-claude)

Copies skills FROM global locations INTO the repo. Always copies (not symlinks) since the repo is the destination. Useful for importing skills created outside this repo.

Script Flags

Append category or skill names after flags to target specific ones:

$SCRIPT --link --to-claude meta roles    # Link only meta/ and roles/
$SCRIPT --from-cursor shell              # Pull only the shell skill

How It Works

Linking: For Claude Code, discovers every individual skill within category directories and creates a flattened symlink for each (e.g., ~/.claude/skills/skill-review → repo/skills/meta/skill-review). For Cursor, creates category-level symlinks. If the target already exists as a real directory, warns before replacing.

Status detection: Checks each expected location and reports whether it's a symlink (and where it points), a copy, or missing. Also detects broken symlinks.

Non-repo skills are safe: The script only manages categories that exist in this repo. Skills like ~/.claude/skills/builtWithAgent/ or Cursor's native skills are never touched.

After Linking

Once linked, skills are available automatically:

• Claude Code: Skills in ~/.claude/skills/ are picked up by new sessions
• Cursor: Skills in ~/.cursor/skills-cursor/ appear in all workspaces

Edit any skill in the repo and the change is live immediately — no sync step needed.

To verify: $SCRIPT --status