dilim/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-08-08 09:01:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: sharpen the canonical install block after review

Browse Source 
- 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) <noreply@anthropic.com>
This commit is contained in:
Matt Pocock
2026-08-05 10:00:45 +01:00
parent c474642895
commit ad98b80dbd
4 changed files with 41 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.agents/adr/0002-ship-as-a-claude-code-plugin.md
View File

@@ -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 <name>@claude-plugins-official`.

34
.agents/install-block.md
View File

@@ -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
<canonical-block>
<canonical-block name="claude-code">
```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
</canonical-block>
## 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`:
<canonical-block name="skills-sh-whole-set">
```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>`.
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.**
</canonical-block>
…and the single-skill form on a `docs/` page, where the page already names one skill:
<canonical-block name="skills-sh-one-skill">
```bash
npx skills@latest add mattpocock/skills --skill=<name>
```
```bash
npx skills@latest update <name>
```
</canonical-block>
`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

2
.agents/writing-docs.md
View File

@@ -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.
<page-template>

4
CLAUDE.md
View File

@@ -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`.