--- id: 901527 card_url: "https://mdrss.com/software-craft/developer-tooling/901527" permalink_url: "https://mdrss.com/m/901527" thread_url: "https://mdrss.com/s/software-craft" markdown_url: "https://mdrss.com/software-craft/developer-tooling/901527/901527.md" title: "mattpocock/skills / CLAUDE.md — The repository contract, auto-loaded by Claude Code and reachable as AGENTS" annotation: "The repository contract, auto-loaded by Claude Code and reachable as AGENTS.md through a symlink so Codex-style agents read the same file. Defines the five skill buckets, the promotion rules that keep README, plugin manifest and docs in sync, and the invocation model." state: published thread: software-craft domain: software-craft category: developer-tooling type: guide tags: ["mattpocock-skills", "agent-skills", "skill-md", "markdown", "claude-code", "developer-tooling", "software-craft", "collider-club", "for-agents", "claude"] ontology_terms: ["concept:developer-tooling", "org:collider-club"] relation_terms: [] license: "MIT" version: 1 snapshot_at: "2026-08-07T09:26:21.585Z" source_url: "https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/CLAUDE.md" source_kind: "api" platform_scam_risk: 5 platform_evidence_score: 100 evidence_urls: - "https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/CLAUDE.md" - "https://raw.githubusercontent.com/mattpocock/skills/main/CLAUDE.md" - "https://github.com/mattpocock/skills" - "https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/LICENSE" - "https://opensource.org/licenses/MIT" --- > **MDRSS snapshot** · `CLAUDE.md` from [mattpocock/skills](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/CLAUDE.md) · audience: AI agents · License: MIT (Matt Pocock). > > The repository contract, auto-loaded by Claude Code and reachable as AGENTS. > > Relative links are pinned to commit `84fdeffd12f2`. --- Skills are organized into bucket folders under `skills/`: - `engineering/` — daily code work - `productivity/` — daily non-code workflow tools - `misc/` — kept around but rarely used, not promoted - `in-progress/` — beta: public on purpose, feedback wanted, not shipped in the plugin - `deprecated/` — 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/`, `in-progress/`, and `deprecated/` must not appear in either. Install commands are copied verbatim from [.agents/install-block.md](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.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. 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](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.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.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`misc/`, `in-progress/`) use a flat list. Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs//.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-` 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](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.agents/writing-docs.md). A finished page carries four sections — **What it does**, **When to reach for it**, **Common questions**, **It's working if** — and `writing-docs.md` holds the template, the section order, and where to hunt for the questions. Skills in the non-promoted buckets (`misc/`, `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](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/.agents/invocation.md). [`ask-matt`](https://github.com/mattpocock/skills/blob/84fdeffd12f2ee307994d1eb6feb48173b6e0502/skills/engineering/ask-matt/SKILL.md) 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. --- *Snapshot metrics: 3407 B · 24 lines · ~948 tokens · 0 headings · links pinned to 84fdeffd12f2.*