sync-skills v2.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/a58070384bdbd827.

---
name: sync-skills
version: 2.1.0
description: |
  Sync skills between this repo and the global skill directories for Claude Code (~/.claude/skills/) and Cursor (~/.cursor/skills-cursor/) using symlinks (default) or copies. Use when the user wants to link, sync, publish, push, or copy skills globally, check sync status, unlink, or pull a skill from a global location back into the repo. Trigger on "sync skills", "link skills", "publish skills", "skill status", "/sync-skills", "are my skills linked", "unlink skills".
requires_agent_teams: false
requires_claude_code: true
min_plan: starter
owns:
  directories: ["skills/workflows/sync-skills/"]
  patterns: []
  shared_read: ["skills/"]
allowed-tools: ["Read", "Bash"]
composes_with: ["skill-update", "skill-review"]
spawned_by: []
---

# 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

| Location | Path | Used by |
| -------- | ---- | ------- |
| Repo (source of truth) | `skills/` | This workspace |
| Claude Code (global) | `~/.claude/skills/` | All Claude Code projects |
| Cursor (global) | `~/.cursor/skills-cursor/` | All Cursor workspaces |

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

```bash
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

| Flag | Purpose |
| ---- | ------- |
| `--link` | Create symlinks (default for `--to-*` operations) |
| `--copy` | Copy files instead of symlinking |
| `--unlink` | Remove symlinks to repo (restores global locations to independent state) |
| `--to-cursor` | Target `~/.cursor/skills-cursor/` |
| `--to-claude` | Target `~/.claude/skills/` |
| `--to-all` | Target both Claude Code and Cursor |
| `--from-cursor` | Pull from Cursor into repo |
| `--from-claude` | Pull from Claude Code into repo |
| `--from-all` | Pull from both |
| `--status` | Show what's linked, copied, or missing across all locations |
| `--clean` | Remove broken symlinks from global locations |
| `--dry-run` | Preview what would happen without making changes |
| `-h, --help` | Show help |

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

```bash
$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`