/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
metadata:
  internal: 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`:

{
  "version": 1,
  "last_synced_at": "ISO-8601 timestamp",
  "agents": ["<agent-file>.md", "..."],
  "skills": ["<skill-dir>", "..."]
}

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

Sync algorithm

Pre-flight: if the source is a clean git repo, `git pull --ff-only` first; surface a warning and proceed if pulling fails.

Then, when `<source_repo>/claude-plugins/prompt-engineering/` is missing, decide which of two different situations produced that one signal before doing anything else. A misconfigured path and a retired-upstream plugin look identical from the target side, and treating retirement as misconfiguration is what strands a retirement: the tracked items stay forever, because the only machinery that could remove them refuses to run.

• **Misconfigured path — the default.** `<source_repo>` itself does not resolve, is not a git repository, or is a partial or mid-clone checkout. Abort. Delete nothing, and leave the tracking file untouched.
• **Confirmed upstream removal.** `<source_repo>` resolves to a healthy full clone, and its own history shows the plugin deliberately removed — a commit deleting `claude-plugins/prompt-engineering/`, and a decision record in `<source_repo>/docs/adr/` stating the retirement. Both are required: a directory absent from a healthy clone with no such history is still treated as misconfiguration. On confirmation, run the sync with an empty source listing — every tracked item becomes eligible for deletion under the ordinary `tracked − source` rule, the `.agents/` mirror symlinks go with them, and the tracking file is left with empty `agents` and `skills` arrays. Add the removed components to the retirement denylist in the same change, so a stale checkout cannot reintroduce them, and record the propagation in this repo's own `docs/adr/`.

When the evidence for removal is not available — no access to the source repo's history, or history that does not settle it — take the misconfigured-path branch. Aborting costs a stale copy that a later run fixes; deleting on a wrong reading costs files no run restores.

For each component (agents/skills):

• **Copy** every source item over its target path. Skip if target is a symlink. **Skip retired items** (see denylist below) even when an older upstream checkout still ships them.
• **Re-apply local metadata** after copying: every non-symlink synced skill's `SKILL.md` must carry `metadata:` / `internal: true` in its frontmatter — add it back when the upstream copy lacks it. Synced skills are repo-maintenance tooling in this repo; the flag keeps skill pickers and directory scrapers from listing them as product skills.
• **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 **minus the denylist**.

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

**Retirement denylist** (never copy or track, regardless of upstream):

| Component | Why it may not come back | |-----------|--------------------------| | `skills/prompt-engineering` | manifest-dev-tools ships its own, as a plugin-owned symlink at `.claude/skills/prompt-engineering` | | `agents/prompt-reviewer.md` | manifest-dev ships **zero agents**; `review-prompt` covers the capability as a plugin-owned symlink at `.claude/skills/review-prompt` | | `agents/prompt-compression-verifier.md` | retired upstream 2026-08-17 | | `agents/prompt-token-efficiency-verifier.md` | retired upstream 2026-08-17 | | `skills/auto-optimize-prompt` | retired upstream 2026-08-17 | | `skills/compress-prompt` | retired upstream 2026-08-17 | | `skills/optimize-prompt-token-efficiency` | retired upstream 2026-08-17 |

The last five were retired as *capability lost, not capability moved* — there is no replacement to point at, and an older upstream checkout that still ships them must not reintroduce them. All seven are already dropped from the tracked set.

.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 sam