# mattpocock/skills: the `.md` map — 35 agent skills, humans and agents separated

[mattpocock/skills](https://github.com/mattpocock/skills) is Matt Pocock's working `.agents` directory, published as-is: "Skills for Real Engineers." It is not a library — it is a set of instructions an AI coding agent loads and follows.

## Repository metrics

| Metric | Value |
|---|---|
| Files (blobs) | 151 |
| Of which `.md` | **101 (66% of files, 88% of bytes)** — 580,210 B |
| `SKILL.md` files | **35**, across five buckets |
| Human docs pages (`docs/`) | 25 files, 249,917 B |
| License | **MIT © Matt Pocock — one zone, no nested exceptions** |
| Created / last push | 3 Feb 2026 / 6 Aug 2026 |
| Stars / forks | 207,868 / 17,946 |

## The five buckets

Skills live under `skills/<bucket>/<name>/SKILL.md`. The bucket decides whether a skill is promoted — shipped in the plugin, listed in the README, and given a docs page.

| Bucket | Count | Status |
|---|---:|---|
| `engineering/` | 18 | Promoted — daily code work |
| `productivity/` | 7 | Promoted — daily non-code workflow |
| `misc/` | 4 | Kept, not promoted |
| `in-progress/` | 6 | Beta, public on purpose, feedback wanted |
| `deprecated/` | 0 | No longer used |

**engineering:** ask-matt, code-review, codebase-design, diagnosing-bugs, domain-modeling, grill-with-docs, implement, improve-codebase-architecture, prototype, research, resolving-merge-conflicts, setup-matt-pocock-skills, tdd, to-spec, to-tickets, triage, wayfinder, wizard

**productivity:** grill-me, grilling, handoff, teach, to-questionnaire, wait-what, writing-for-agents

## Three ideas worth stealing

**1. One file, two names.** `AGENTS.md` is a 9-byte symlink pointing at `CLAUDE.md`. Claude Code reads one name, Codex-style agents read the other, and there is only ever one file to maintain — no drift between two copies of the same rules.

**2. A shared vocabulary file.** `CONTEXT.md` is a domain glossary: it defines *Issue tracker*, *Issue*, *Decision ticket* and *Triage role*, lists the synonyms to avoid, and records ambiguities that were resolved (for example, "backlog" used to mean both the tool and the body of work — the tool is now always the Issue tracker). Agent and human end up speaking one language instead of drifting.

**3. Two invocation modes, declared explicitly.** Every `SKILL.md` is either **user-invoked** — reachable only by a human via slash command, enforced with `disable-model-invocation: true` plus a policy flag — or **model-invoked**, which the agent may trigger on its own. Nothing is ambiguous about who can fire what.

## The promotion contract

`CLAUDE.md` is not prose; it is a set of invariants that keep the repository from rotting:

```
skill in engineering/ or productivity/  →  MUST appear in top-level README.md
                                        →  MUST appear in .claude-plugin/plugin.json
                                        →  MUST have a docs page at docs/<bucket>/<name>.md
skill in misc/, in-progress/, deprecated/  →  MUST NOT appear in either
```

Docs pages carry four fixed sections: *What it does*, *When to reach for it*, *Common questions*, *It's working if*. Install instructions are copied verbatim from a single source block, so they cannot drift between README and docs.

`ask-matt` is the router: it maps every user-reachable skill and how they relate. The repository states the rule plainly — a router that never mentions a new skill, or still routes to a removed one, is a router that lies.

## Licensing

One `LICENSE` at the root: **MIT © Matt Pocock, 2026**. No nested license files, no copyleft subtree, no vendored third-party code with a different holder. Reuse is straightforward — which is not the case for every skills pack.

## How the metrics were verified

File sizes and modes come from the Git Trees API (`/repos/mattpocock/skills/git/trees/main?recursive=1`, 240 entries, `truncated: false`). Skill counts were derived by grouping every path ending in `SKILL.md` by its bucket directory. Token figures are a heuristic of one token per four characters. Relative links in every published snapshot are rewritten to absolute GitHub URLs pinned to the source commit.

Data captured 7 August 2026.