--- id: 901534 card_url: "https://mdrss.com/software-craft/developer-tooling/901534" permalink_url: "https://mdrss.com/m/901534" thread_url: "https://mdrss.com/s/software-craft" markdown_url: "https://mdrss.com/software-craft/developer-tooling/901534/901534.md" title: "mattpocock/skills / .agents/adr/0002-ship-as-a-claude-code-plugin.md — Architecture decision record explaining why the collection ships as a" annotation: "Architecture decision record explaining why the collection ships as a Claude Code plugin and why no Codex plugin exists yet. Useful context for anyone packaging their own skills for more than one harness." state: published thread: software-craft domain: software-craft category: developer-tooling type: reference tags: ["mattpocock-skills", "agent-skills", "skill-md", "markdown", "claude-code", "developer-tooling", "software-craft", "collider-club", "for-agents", "0002-ship-as-a-claude-code-plugin"] ontology_terms: ["concept:developer-tooling", "org:collider-club"] relation_terms: [] license: "MIT" version: 1 snapshot_at: "2026-08-07T09:27:01.780Z" source_url: "https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.agents/adr/0002-ship-as-a-claude-code-plugin.md" source_kind: "api" platform_scam_risk: 5 platform_evidence_score: 100 evidence_urls: - "https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.agents/adr/0002-ship-as-a-claude-code-plugin.md" - "https://raw.githubusercontent.com/mattpocock/skills/main/.agents/adr/0002-ship-as-a-claude-code-plugin.md" - "https://github.com/mattpocock/skills" - "https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/LICENSE" - "https://opensource.org/licenses/MIT" --- > **MDRSS snapshot** · `.agents/adr/0002-ship-as-a-claude-code-plugin.md` from [mattpocock/skills](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.agents/adr/0002-ship-as-a-claude-code-plugin.md) · audience: AI agents · License: MIT (Matt Pocock). > > Architecture decision record explaining why the collection ships as a Claude Code plugin and why no Codex plugin exists yet. > > Relative links are pinned to commit `84fdeffd12f2`. --- # Ship the skill set as a native Claude Code plugin; defer a native Codex plugin These skills have always been installable via [skills.sh](https://skills.sh/mattpocock/skills) (`npx skills add mattpocock/skills`), which copies editable skill files into a user's project across Claude Code, Codex, and other Agent-Skills-standard harnesses. A recurring request is a **plug-and-play** distribution: subscribe to the set as a read-only, always-current bundle you don't edit, rather than a fork you own. That is exactly what native plugin systems provide. We ship a native **Claude Code plugin** and, for now, **defer** a native **Codex plugin**. The split is forced by how each ecosystem's plugin manifest selects skills, against this repo's bucketed layout. ## The constraint: bucketed skills vs. single-path selection Skills live in bucket folders under `skills/` — `engineering/` and `productivity/` are **promoted** (shipped); `misc/`, `personal/`, `in-progress/`, and `deprecated/` are **not**. A plugin must expose only the promoted set, which spans two of those bucket folders. - **Claude Code** — `.claude-plugin/plugin.json` accepts `skills` as an **array of explicit skill-directory paths**. We list the promoted skills one by one, exclude everything else with zero ambiguity, and add `.claude-plugin/marketplace.json` so the repo is its own single-plugin marketplace. Verified end to end: `claude plugin validate . --strict` passes, and `marketplace add` → `install` resolves all promoted skills. - **Codex** — `.codex-plugin/plugin.json` accepts `skills` only as a **single path string** (arrays are rejected with `missing or invalid plugin.json`), and Codex discovers `SKILL.md` files recursively under it. There is no way to name two bucket folders, or to curate a subset, from one path. Two escape hatches were tested and rejected: - Pointing at `./skills/` would also ship `deprecated/`, `in-progress/`, `personal/`, and `misc/` — retired, draft, and personal skills we deliberately don't promote. - A curated flat directory of **symlinks** into the buckets does not survive install: Codex copies the plugin tree into its cache and **drops symlinks**, so the skills arrive empty. The only robust ways to give Codex a single promoted-only path are (a) **restructure** so `skills/` contains only promoted skills (moving the non-promoted buckets out — a large blast radius across `CLAUDE.md`, `scripts/link-skills.sh`, the bucket READMEs, and the local dev workflow that relies on `in-progress/` and `personal/`), or (b) **commit duplicate copies** of promoted skills into a flat directory (a sync burden and a second source of truth). Both are structural decisions, not something to bundle into shipping the Claude plugin. This is very likely the original, half-remembered reason a plugin wasn't shipped earlier: the manifest formats didn't cleanly express a curated subset of a bucketed repo. ## Decision - Ship the **Claude Code plugin** now (`.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json`), curated to the promoted set, as the headline v1.2 deliverable. - Keep **skills.sh** as the universal installer — it already serves Codex and other harnesses today, so no Codex user is left without an install path. - **Defer** the native Codex plugin until we decide between restructuring `skills/` to promoted-only vs. committing a generated flat copy. Revisit when Codex either supports a `skills` array / include-list or preserves symlinks on install. ## Invariants this creates - Every promoted skill has an entry in `.claude-plugin/plugin.json`'s `skills` array (this already stood as a `CLAUDE.md` rule; it now also gates the plugin's contents). - `.claude-plugin/plugin.json`'s `version` tracks `package.json`'s version — bump both together on release. Claude uses the plugin `version` to decide when installed users see an update. ## Update, 2026-08-05 `mattpocock-skills` was accepted into **Claude Code's official marketplace** — configured name `claude-plugins-official`, source repo `anthropics/claude-plugins-official` — which every Claude Code install has by default. `claude plugins install mattpocock-skills` is now the documented route, and the `marketplace add` → `install` path above is superseded. The install wording lives in [.agents/install-block.md](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.agents/install-block.md). The official listing points at this repo's git URL and reads `.claude-plugin/plugin.json` directly, so it does not depend on `.claude-plugin/marketplace.json`. That file is retained only as a fallback for installing the repo directly (an unreleased commit, or a fork). Verified 2026-08-05, on Claude Code 2.1.222, against the live listing: - `claude plugins install mattpocock-skills` resolves with no marketplace added first, and reports `mattpocock-skills@claude-plugins-official`. - `claude plugin details mattpocock-skills` then reports version 1.2.0 and loads the promoted skills. - The listing's `source` is `{"source": "url", "url": "https://github.com/mattpocock/skills.git", "sha": …}` — the **sha is pinned**, so a release reaches installed users when that pin moves, not the moment we tag. At the time of writing the pin sits two commits behind `main`, which is why it lists 22 skills rather than the 24 in `plugin.json`. - The in-session `/plugin install mattpocock-skills` was **not** exercised — `/plugin` is unavailable in headless (`claude -p`) sessions. It runs the same resolver as the CLI, and the documented example form is `/plugin install @claude-plugins-official`. --- *Snapshot metrics: 5560 B · 42 lines · ~1405 tokens · 5 headings · links pinned to 84fdeffd12f2.*