docs: tell one true install story (official marketplace)

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) <noreply@anthropic.com>

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

.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)
+
+<canonical-block>
+
+```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.
+
+</canonical-block>
+
+## 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=<name>`; to refresh it later, `npx skills update <name>`.
+
+## 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.

.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.
+
 <page-template>
 
 Quickstart: