Sync Claude Code Plugins

---
name: sync-claude-code-plugins
description: 'Sync the prompt-engineering plugin from a local clone of claude-code-plugins into .claude/ so the repo is self-contained for isolated/web environments. Copies agents/skills, removes only previously-synced items that disappeared upstream. Other content in .claude/ is left alone. Use when asked to sync claude-code-plugins, pull prompt-engineering, refresh prompt-engineering plugin.'
user-invocable: true
---

**User request**: $ARGUMENTS

Sync prompt-engineering plugin components from a local sibling clone of `claude-code-plugins` into this repo's `.claude/` directory. The plugin OWNS only the files it ships — other content in `.claude/agents/` and `.claude/skills/` (manifest-dev sync, KB skills, anything else) must be left alone.

## Source & Target

| Role | Path |
|------|------|
| Source repo | `../claude-code-plugins` (relative to this repo's root) |
| Source components | `<source_repo>/claude-plugins/prompt-engineering/` |
| Target | `.claude/` in this repo |
| Tracking file | `.claude/.claude-code-plugins-sync.json` |

## Sync scope

| Component | Source dir | Target dir |
|-----------|-----------|------------|
| Agents | `agents/` | `.claude/agents/` |
| Skills | `skills/` | `.claude/skills/` |

prompt-engineering ships no hooks today.

## Territory model

**Deletion invariant**: only items in `tracked` (the previously-synced set) are eligible for removal when they disappear upstream. Items never in `tracked` are invisible — that's how project-local content stays safe.

The tracked set lives in `.claude/.claude-code-plugins-sync.json`:

```json
{
  "version": 1,
  "last_synced_at": "ISO-8601 timestamp",
  "agents": ["prompt-reviewer.md", "..."],
  "skills": ["prompt-engineering", "..."]
}
```

First run (file missing): `tracked` is empty, no deletions happen, file is written at end.

## Sync algorithm

Pre-flight: abort if `<source_repo>/claude-plugins/prompt-engineering/` is missing — silent absence is a misconfigured path, not upstream removal. Do not delete on this signal. If the source is a clean git repo, `git pull --ff-only` first; surface a warning and proceed if pulling fails.

For each component (agents/skills):

- **Copy** every source item over its target path. Skip if target is a symlink.
- **Delete** items in `tracked − source` from target. Skip if target is a symlink, doesn't exist, or is the `sync-claude-code-plugins` skill itself.
- **Refresh** `.claude/.claude-code-plugins-sync.json` with the current source listing.

Source listing excludes `README.md` and `.claude-plugin/` (plugin metadata, not content).

## .agents mirror

After each sync, ensure `.agents/skills/<name>` is a symlink to `../../.claude/skills/<name>` for every tracked skill, and remove the symlink for any skill removed from `tracked`. This lets non-Claude coding agents (Codex, etc.) read the same skills without duplicating content. Only skills are mirrored — `.agents/agents/` is out of scope.

- Create the symlink if missing.
- If `.agents/skills/<name>` exists and is not a symlink, skip it — that's project-local content, don't clobber.
- Create `.agents/skills/` if missing, but never `.agents/` itself (the user opts in by creating it).

## Gotchas

- **Source must exist**: missing source path means abort, not "delete all tracked items."
- **Nested skills directory**: source skills live at `skills/prompt-engineering/`, `skills/review-prompt/`, etc. Copy each skill directory into `.claude/skills/<skill-name>/` — don't copy the outer `skills/` folder or you get `.claude/skills/skills/`.
- **Symlinks look like directories to `cp`/`rm`/`find`**: a symlinked target overwritten by `cp -R` corrupts the linked plugin's source files; a symlinked directory deleted by `rm -rf` removes the link, not the plugin, but a recursive find that follows the link will. Use `[ -L path ]` before every overwrite and every delete.

## Output

Summary table per component (agents/skills): items added, updated, removed, symlinks skipped, and removals refused (e.g. due to symlink). Show the net change to the tracking file.

## Never

- Overwrite, remove, or follow into symlinks under `.claude/` — check `[ -L path ]` before every copy, delete, or recursive descent
- Replace a non-symlink at `.agents/skills/<name>` — leave project-local content alone
- Create `.agents/` itself (only manage `.agents/skills/<name>` entries inside an existing `.agents/`)
- Delete items not in the tracked set — even if they're not in source
- Delete the `sync-claude-code-plugins` skill
- Treat a missing source path as upstream removal — abort instead
- Copy plugin metadata (`README.md`, `.claude-plugin/`) or the source repo's own `.claude/` directory
- Modify the source repo (other than the optional `git pull --ff-only`)