Matt PocockandClaude Opus 5
c474642895
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>
3.6 KiB
Skills are organized into bucket folders under skills/:
engineering/— daily code workproductivity/— daily non-code workflow toolsmisc/— kept around but rarely used, not promotedpersonal/— tied to my own setup, not promotedin-progress/— drafts not yet ready to shipdeprecated/— no longer used
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 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.
Each skill entry in the top-level README.md must link the skill name to its SKILL.md.
Each bucket folder has a README.md that lists every skill in the bucket with a one-line description, with the skill name linked to its SKILL.md. The promoted buckets' README.mds and the top-level README.md group entries into User-invoked and Model-invoked; non-promoted bucket README.mds (misc/, personal/) use a flat list.
Skills in engineering/ and productivity/ also have a human-facing docs page at docs/<bucket>/<skill-name>.md (the docs tree mirrors those two bucket folders under skills/). The published URL is https://aihero.dev/skills-<skill-name> regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in engineering/ or productivity/, create or re-sync its docs page following .agents/writing-docs.md. Skills in the non-promoted buckets (misc/, personal/, in-progress/, deprecated/) get no docs page.
Every SKILL.md is either user-invoked (disable-model-invocation: true plus policy.allow_implicit_invocation: false in agents/openai.yaml, reachable only by the human) or model-invoked (model- or user-reachable). See .agents/invocation.md.
ask-matt is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read ask-matt's SKILL.md and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies.
To (re)link every skill into the local harness skill directories (~/.claude/skills, ~/.agents/skills), run scripts/link-skills.sh. Each entry is a symlink into this repo, so a git pull keeps installed skills current; re-run the script after adding, removing, or renaming a skill.