From c474642895f1f643d4701b8a3430391883c364ea Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 09:57:57 +0100 Subject: [PATCH 1/3] docs: tell one true install story (official marketplace) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mattpocock-skills is now listed in Claude Code's official marketplace, so the own-marketplace route is superseded. The queued changeset still documented it, and changeset bodies ship verbatim into CHANGELOG.md — the release would have published a superseded install route as its headline. - Rewrite .changeset/ship-as-claude-plugin.md around `claude plugins install mattpocock-skills`. - Add .agents/install-block.md as the single source for install wording, so the docs pass has one true thing to copy. - Point .agents/writing-docs.md and CLAUDE.md at it. - Note the official listing in ADR 0002, and record that it reads plugin.json directly and does not depend on marketplace.json. .claude-plugin/marketplace.json is kept as a fallback for direct-repo installs; nothing in CI or scripts references it. Refs mattpocock/personal-wiki#250 Co-Authored-By: Claude Opus 5 (1M context) --- .../adr/0002-ship-as-a-claude-code-plugin.md | 4 ++ .agents/install-block.md | 41 +++++++++++++++++++ .agents/writing-docs.md | 2 + .changeset/ship-as-claude-plugin.md | 17 +++++--- CLAUDE.md | 2 +- 5 files changed, 60 insertions(+), 6 deletions(-) create mode 100644 .agents/install-block.md diff --git a/.agents/adr/0002-ship-as-a-claude-code-plugin.md b/.agents/adr/0002-ship-as-a-claude-code-plugin.md index 8902f9d..1056836 100644 --- a/.agents/adr/0002-ship-as-a-claude-code-plugin.md +++ b/.agents/adr/0002-ship-as-a-claude-code-plugin.md @@ -26,3 +26,7 @@ The only robust ways to give Codex a single promoted-only path are (a) **restruc - 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** (`anthropics/claude-plugins-official`), which every Claude Code install has configured by default. `claude plugins install mattpocock-skills` is now the documented route, and the `marketplace add` → `install` path above is superseded. 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). The install wording lives in [.agents/install-block.md](../install-block.md). diff --git a/.agents/install-block.md b/.agents/install-block.md new file mode 100644 index 0000000..497b8b2 --- /dev/null +++ b/.agents/install-block.md @@ -0,0 +1,41 @@ +# The canonical install block + +One install story, one wording. `README.md`, `.changeset/*`, and every page under `docs/` say **this** and nothing else. If the install route changes, change it here first, then propagate. + +`mattpocock-skills` is listed in **Claude Code's official marketplace** (`claude-plugins-official`), which every Claude Code install has configured out of the box. There is no marketplace to add first, and official-marketplace plugins auto-update in the background. + +## Claude Code (the plugin) + + + +```bash +claude plugins install mattpocock-skills +``` + +Or, from inside a session: + +``` +/plugin install mattpocock-skills +``` + +It's in Claude Code's official marketplace, so there's nothing to add first, and updates arrive automatically. + + + +## Codex, and other agents (skills.sh) + +The plugin is Claude Code only. Everywhere else, [skills.sh](https://skills.sh/mattpocock/skills) copies editable skill files into the project: + +```bash +npx skills@latest add mattpocock/skills +``` + +For a single skill, `npx skills add mattpocock/skills --skill=`; to refresh it later, `npx skills update `. + +## The two routes are exclusive + +The plugin is a managed, read-only bundle you subscribe to. skills.sh writes files you own and edit. Installing both leaves the user with every skill twice — always say "pick one". + +## Not the install story + +`.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace (`/plugin marketplace add mattpocock/skills`, then `/plugin install mattpocock-skills@mattpocock`). The official listing supersedes it. It is kept as a fallback for installing the repo directly — an unreleased commit, or a fork — and is **not** documented to users. diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index c3bfc83..c071a55 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -14,6 +14,8 @@ There is no H1 — the published page takes its title from the slug. Fill the template below. The **fixed frame** (Quickstart block, source link, `## What it does`, `## When to reach for it`, `## Where it fits`) appears on every page. The **adaptable middle** — `## Prerequisites` and the free-form substance sections — carries only what this particular skill earns; delete the rest. +Install commands are not written per page. Copy them verbatim from [the canonical install block](./install-block.md) — it is the single source for how anyone installs these skills, and a page that words it differently is a page that tells a second story. + Quickstart: diff --git a/.changeset/ship-as-claude-plugin.md b/.changeset/ship-as-claude-plugin.md index b58c0d1..7452d37 100644 --- a/.changeset/ship-as-claude-plugin.md +++ b/.changeset/ship-as-claude-plugin.md @@ -2,11 +2,18 @@ "mattpocock-skills": minor --- -Ship the skill set as a native **Claude Code plugin**. The repo is now its own single-plugin marketplace, so you can subscribe to the promoted skills as a managed, read-only bundle instead of copying editable files: +Ship the skill set as a native **Claude Code plugin**, listed in Claude Code's official marketplace. You can now subscribe to the promoted skills as a managed, read-only bundle instead of copying editable files: -``` -/plugin marketplace add mattpocock/skills -/plugin install mattpocock-skills@mattpocock +```bash +claude plugins install mattpocock-skills ``` -`.claude-plugin/plugin.json` gains full marketplace metadata (version, description, author, license, keywords) and a sibling `.claude-plugin/marketplace.json` lists the plugin. `skills.sh` remains the universal installer (and the path for Codex and other harnesses today); a native Codex plugin is deferred — see `.agents/adr/0002-ship-as-a-claude-code-plugin.md` for why. +Or, from inside a session: + +``` +/plugin install mattpocock-skills +``` + +There is no marketplace to add first — the official marketplace is configured by default. + +`.claude-plugin/plugin.json` carries the full plugin metadata (version, description, author, license, keywords) and the explicit list of promoted skills. `skills.sh` remains the universal installer (and the path for Codex and other harnesses today); a native Codex plugin is deferred — see `.agents/adr/0002-ship-as-a-claude-code-plugin.md` for why. diff --git a/CLAUDE.md b/CLAUDE.md index e2c7d0b..5ca428f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ Skills are organized into bucket folders under `skills/`: Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `personal/`, `in-progress/`, and `deprecated/` must not appear in either. -The repo is also its own single-plugin Claude Code marketplace: `.claude-plugin/marketplace.json` lists the one `mattpocock-skills` plugin. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md). +`mattpocock-skills` is listed in **Claude Code's official marketplace** (`claude-plugins-official`), which is the one install route we document — see [.agents/install-block.md](./.agents/install-block.md) for the exact wording, and use it verbatim rather than rewording it per page. The repo is *also* its own single-plugin marketplace (`.claude-plugin/marketplace.json` lists the one `mattpocock-skills` plugin), kept only as a fallback for installing the repo directly; the official listing does not depend on it. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md). Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`. From ad98b80dbd96ce60eaadebb8d42bca4af131d0fd Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 10:00:45 +0100 Subject: [PATCH 2/3] docs: sharpen the canonical install block after review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - install-block.md: state the invariant as a requirement rather than as already-true (docs/ is brought into line downstream); mark all three canonical snippets, not just the Claude Code one; pin the `skills@latest` spelling; restore the `setup-matt-pocock-skills` instruction the whole-set form carries; cite the docs source for the auto-update claim. - writing-docs.md: say plainly that the template's Quickstart is the older wording, so the file no longer contradicts itself. - CLAUDE.md: split the paragraph, stop restating the fallback rationale. - ADR 0002: record what was actually verified, on which version, and the two things that were not — the pinned sha in the official listing, and the in-session slash command. Refs mattpocock/personal-wiki#250 Co-Authored-By: Claude Opus 5 (1M context) --- .../adr/0002-ship-as-a-claude-code-plugin.md | 11 +++++- .agents/install-block.md | 34 +++++++++++++++---- .agents/writing-docs.md | 2 +- CLAUDE.md | 4 ++- 4 files changed, 41 insertions(+), 10 deletions(-) diff --git a/.agents/adr/0002-ship-as-a-claude-code-plugin.md b/.agents/adr/0002-ship-as-a-claude-code-plugin.md index 1056836..e5c13ea 100644 --- a/.agents/adr/0002-ship-as-a-claude-code-plugin.md +++ b/.agents/adr/0002-ship-as-a-claude-code-plugin.md @@ -29,4 +29,13 @@ The only robust ways to give Codex a single promoted-only path are (a) **restruc ## Update, 2026-08-05 -`mattpocock-skills` was accepted into **Claude Code's official marketplace** (`anthropics/claude-plugins-official`), which every Claude Code install has configured by default. `claude plugins install mattpocock-skills` is now the documented route, and the `marketplace add` → `install` path above is superseded. 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). The install wording lives in [.agents/install-block.md](../install-block.md). +`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](../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`. diff --git a/.agents/install-block.md b/.agents/install-block.md index 497b8b2..26f511e 100644 --- a/.agents/install-block.md +++ b/.agents/install-block.md @@ -1,12 +1,12 @@ # The canonical install block -One install story, one wording. `README.md`, `.changeset/*`, and every page under `docs/` say **this** and nothing else. If the install route changes, change it here first, then propagate. +One install story, one wording. `README.md`, `.changeset/*`, and every page under `docs/` must say **this** and nothing else. Change it here first, then propagate. -`mattpocock-skills` is listed in **Claude Code's official marketplace** (`claude-plugins-official`), which every Claude Code install has configured out of the box. There is no marketplace to add first, and official-marketplace plugins auto-update in the background. +`mattpocock-skills` is listed in **Claude Code's official marketplace** — configured name `claude-plugins-official`, source repo `anthropics/claude-plugins-official` — which every Claude Code install has out of the box. There is no marketplace to add first. Official Anthropic marketplaces have auto-update enabled by default ([discover-plugins](https://code.claude.com/docs/en/discover-plugins)), so "updates arrive automatically" is a true claim, not a hope. -## Claude Code (the plugin) +## Claude Code — the plugin - + ```bash claude plugins install mattpocock-skills @@ -22,15 +22,35 @@ It's in Claude Code's official marketplace, so there's nothing to add first, and -## Codex, and other agents (skills.sh) +## Codex, and other agents — skills.sh -The plugin is Claude Code only. Everywhere else, [skills.sh](https://skills.sh/mattpocock/skills) copies editable skill files into the project: +The plugin is Claude Code only. Everywhere else, [skills.sh](https://skills.sh/mattpocock/skills) copies editable skill files into the project. Use the whole-set form on `README.md`: + + ```bash npx skills@latest add mattpocock/skills ``` -For a single skill, `npx skills add mattpocock/skills --skill=`; to refresh it later, `npx skills update `. +Pick the skills you want, and which coding agents to install them on. **The installer lets you choose which skills to take — make sure `setup-matt-pocock-skills` is one of them.** + + + +…and the single-skill form on a `docs/` page, where the page already names one skill: + + + +```bash +npx skills@latest add mattpocock/skills --skill= +``` + +```bash +npx skills@latest update +``` + + + +`skills@latest` is the pinned spelling in all three. The Quickstart template in [writing-docs.md](./writing-docs.md), and the 24 pages under `docs/`, still carry the older bare `npx skills …`; the docs pass brings them into line. ## The two routes are exclusive diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index c071a55..fda0c7a 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -14,7 +14,7 @@ There is no H1 — the published page takes its title from the slug. Fill the template below. The **fixed frame** (Quickstart block, source link, `## What it does`, `## When to reach for it`, `## Where it fits`) appears on every page. The **adaptable middle** — `## Prerequisites` and the free-form substance sections — carries only what this particular skill earns; delete the rest. -Install commands are not written per page. Copy them verbatim from [the canonical install block](./install-block.md) — it is the single source for how anyone installs these skills, and a page that words it differently is a page that tells a second story. +Install commands are not written per page. Copy them verbatim from [the canonical install block](./install-block.md) — it is the single source for how anyone installs these skills, and a page that words it differently is a page that tells a second story. The Quickstart block in the template below is the older wording and does not yet match; the docs pass replaces it from the canonical block. diff --git a/CLAUDE.md b/CLAUDE.md index 5ca428f..05b501d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,9 @@ Skills are organized into bucket folders under `skills/`: Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `personal/`, `in-progress/`, and `deprecated/` must not appear in either. -`mattpocock-skills` is listed in **Claude Code's official marketplace** (`claude-plugins-official`), which is the one install route we document — see [.agents/install-block.md](./.agents/install-block.md) for the exact wording, and use it verbatim rather than rewording it per page. The repo is *also* its own single-plugin marketplace (`.claude-plugin/marketplace.json` lists the one `mattpocock-skills` plugin), kept only as a fallback for installing the repo directly; the official listing does not depend on it. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md). +`mattpocock-skills` is listed in **Claude Code's official marketplace** (`claude-plugins-official`), and that is the one install route we document. Never reword an install command in place — copy it verbatim from [.agents/install-block.md](./.agents/install-block.md), which is the single source for install wording. + +The repo is *also* its own single-plugin marketplace: `.claude-plugin/marketplace.json` lists the one `mattpocock-skills` plugin. The official listing does not depend on it, and it is not documented to users — it survives only as the fallback described in the install block. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md). Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`. From 4f6e25d91efe883cf0f55b5782e6527ebd3dcc63 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 10:15:18 +0100 Subject: [PATCH 3/3] docs: shrink the CLAUDE.md change to the pointer that earns it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md is always-loaded, so every word costs on every turn. The edit had grown it by ~65 words, nearly all of which paid load without changing behaviour: - The official-marketplace sentence was exposition — a fact the pointer target already carries. - "Never reword an install command" steered by prohibition, which makes the banned behaviour more available, not less. - The fallback rationale was a third copy of what install-block.md owns. - The paragraph split doubled the surface with no branch behind it. What remains is the one line that does work — the context pointer, front-loaded on its trigger — leaving CLAUDE.md 10 words longer than before rather than 65. Refs mattpocock/personal-wiki#250 Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 05b501d..c870241 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,9 +9,7 @@ Skills are organized into bucket folders under `skills/`: Every skill in `engineering/` or `productivity/` (the **promoted** buckets) must have a reference in the top-level `README.md` and an entry in `.claude-plugin/plugin.json`'s `skills` array (the Claude Code plugin ships exactly the promoted set). Skills in `misc/`, `personal/`, `in-progress/`, and `deprecated/` must not appear in either. -`mattpocock-skills` is listed in **Claude Code's official marketplace** (`claude-plugins-official`), and that is the one install route we document. Never reword an install command in place — copy it verbatim from [.agents/install-block.md](./.agents/install-block.md), which is the single source for install wording. - -The repo is *also* its own single-plugin marketplace: `.claude-plugin/marketplace.json` lists the one `mattpocock-skills` plugin. The official listing does not depend on it, and it is not documented to users — it survives only as the fallback described in the install block. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md). +Install commands are copied verbatim from [.agents/install-block.md](./.agents/install-block.md). `.claude-plugin/marketplace.json` makes the repo its own single-plugin marketplace — a fallback the install block explains, not the documented route. When bumping the release version, keep `.claude-plugin/plugin.json`'s `version` in sync with `package.json`'s — Claude uses the plugin `version` to decide when installed users see an update. Run `claude plugin validate . --strict` after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in [.agents/adr/0002-ship-as-a-claude-code-plugin.md](./.agents/adr/0002-ship-as-a-claude-code-plugin.md). Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`.