mattpocock/skills: Matt Pocock's Agent Skills for TypeScript and Real Engineering

The problem mattpocock/skills targets: agents that build the wrong thing

The README frames the repository around three named failure modes. The first is misalignment: you think the agent knows what you want, then you see what it built. The second is verbosity, where an agent dropped into an unfamiliar project guesses at the jargon and uses twenty words where one would do. The third is code that simply does not run, which the README attributes to missing feedback loops such as static types and browser access.

The intended audience is narrow and specific. This is for engineers who already use a coding agent on a real codebase and who want to stay in control of the process. The README contrasts the approach with GSD, BMAD and Spec-Kit, which it says try to help by owning the process, and in doing so take away your control and make bugs in the process hard to resolve. The stated alternative is a set of skills that are small, easy to adapt and composable, and that work with any model.

That framing is also the main constraint. If you want a tool that imposes a workflow on your team, this repository deliberately does not do that. The README's own instructions tell you to hack around with the skills and make them your own, which is a reasonable posture for a solo engineer and a harder one to standardise across a team.

How the skills are structured and what the installer actually writes

The repository is a collection of skill directories under skills/, grouped by area such as productivity and engineering, each holding a SKILL.md file. The README links directly to paths like skills/productivity/grill-me/SKILL.md and skills/engineering/grill-with-docs/SKILL.md, so the individual skills are plain documents you can read in the repository before installing anything.

There are two distribution paths, and the README describes them as two philosophies rather than two options. The Claude Code plugin installs the whole set as a managed, read-only bundle that updates when the author ships, so you subscribe rather than fork. The skills.sh installer copies editable skill files into your project, so you can modify them. The README is explicit that installing both leaves you with every skill twice, which is the kind of detail that usually only appears after someone has hit it.

Versioning is handled through Changesets. The package.json defines a version script that runs changeset version and then node scripts/sync-plugin-version.mjs, plus a check-plugin-version script that runs the same file with a --check flag. That suggests the plugin version and the package version are kept in sync by a script rather than by hand, which matters if you pin a version.

The setup step is a skill in its own right. Running /setup-matt-pocock-skills once per repository asks which issue tracker you want (GitHub, Linear, or local files), what labels you apply when triaging tickets, and where to save documentation. The /triage skill depends on those labels, so the setup step is not optional decoration.

Installing mattpocock/skills and running the first grilling session

The README calls the install a thirty-second setup. On Claude Code, the plugin comes from the official marketplace, so there is nothing to add first. Run this from your shell:

claude plugins install mattpocock-skills

The same install is available from inside a session with /plugin install mattpocock-skills. Updates arrive automatically because the bundle is managed and read-only.

For Codex and other agents, the installer is an npm package. It prompts you to pick skills and to choose which coding agents to install them on:

npx skills@latest add mattpocock/skills

The README warns that the installer lets you choose which skills to take, so setup-matt-pocock-skills must be one of them. If you want the files in your repository rather than a managed bundle, you run the same command on any agent, including Claude Code, and it writes the skills in as ordinary files you own. Nothing updates behind your back, and you pull later changes with npx skills update. A native Codex plugin is listed as on the roadmap in .agents/adr/0002-ship-as-a-claude-code-plugin.md.

Once installed, run the setup skill once per repo:

/setup-matt-pocock-skills

It asks for your issue tracker, your triage labels and where docs should live. After that, the README's most-recommended starting point is a grilling session. For non-code work that is /grill-me; for code, /grill-with-docs, which the README describes as the same idea plus a shared language document and ADRs. The README says to use these every time you want to make a change, which is a strong claim, but it is the author's stated practice rather than a measured result.

Where the shared language idea pays off, and where it does not

The most specific mechanism in the repository is the shared language document, illustrated by CONTEXT.md. The README shows a before-and-after pair: a sentence about a problem when a lesson inside a section of a course is made real, versus the same idea compressed to a problem with the materialization cascade. The claim is that this concision pays off session after session, and the README lists three consequences: consistent naming of variables, functions and files; a codebase that is easier for an agent to navigate; and fewer tokens spent on thinking.

That last point is the one to treat carefully. Token savings are plausible when a project has genuinely dense domain jargon, and much less plausible on a small codebase where the agent already has the whole thing in context. The technique also has a maintenance cost that the README does not discuss: a CONTEXT.md is a document, and documents drift. If the shared language is not updated when the domain changes, the agent will confidently use stale vocabulary, and the failure will look like a naming inconsistency rather than a documentation problem.

The stronger part of the argument is the naming consistency. If files, functions and variables all draw from one glossary, an agent reading the repository has fewer competing signals to reconcile. That benefit does not depend on any token accounting.

A real limitation: the skills depend on a setup step and on your own discipline

The clearest failure mode is visible in the README's own instructions. The /triage skill uses labels, and those labels are collected by /setup-matt-pocock-skills. Install the skills without running setup, or pick a subset of skills in the npx installer that omits setup-matt-pocock-skills, and the workflows that depend on it have nothing to read. The README calls this out, which is a sign it happens.

The second limitation is philosophical and worth stating plainly. The repository rejects process-owning frameworks, and the price of that rejection is that you supply the process. The skills prompt you to grill yourself before coding, to maintain a shared language, and to keep feedback loops tight. None of that is enforced. An agent with these skills installed will still produce misaligned code if you skip the grilling session, and the README's answer to that is a recommendation, not a mechanism.

The third is scope. The description positions the repository around TypeScript, testing, debugging and day-to-day software work, and the visible skills are prompt documents rather than language tooling. If your problem is that your type checker is slow or your test runner is misconfigured, these files will not fix it. They change how you talk to an agent, not how your build behaves.

How this differs from process-owning frameworks like Spec-Kit and BMAD

The README names GSD, BMAD and Spec-Kit as the approaches it is reacting to, and the difference is about who holds the process. Those tools own the workflow: you follow their stages and their artefacts, and in exchange you get a defined path from idea to implementation. The README's objection is that this takes away your control and makes bugs in the process hard to resolve, because the process itself is not yours to edit.

The mattpocock/skills approach inverts that. There is no pipeline to follow. There are small skills you invoke when they fit, and if one behaves badly you open its SKILL.md and change it, at least on the skills.sh install path. The Claude Code plugin path gives up that editability in exchange for automatic updates, which is the opposite trade and worth choosing deliberately.

Neither model is strictly better. A framework is easier to hand to a team that wants a consistent path and does not want to debate prompts. A composable skill set is easier to adapt and harder to standardise. The README's position is that the second is worth the cost, and the repository layout backs that up: the skills are short documents, not an engine.

Maintenance, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-08-06, the same day as the v1.2.3 release. Releases v1.2.0 and v1.2.2 landed on 2026-08-05, so the recent cadence is a cluster of releases in early August rather than a steady stream. The README points readers to a newsletter for changes and new skills, which is where the author says updates are announced.

Upgrade cost depends entirely on which path you chose. On the Claude Code plugin, updates arrive automatically and there is no merge step, but you also cannot keep local edits. On the skills.sh path, files live in your repository as ordinary files you own, nothing updates behind your back, and npx skills update pulls the author's latest changes. That last command is where the cost sits: if you have edited the skills, pulling updates means reconciling your edits, and the README does not document a rollback procedure. The repository does ship a CHANGELOG.md and a .changeset/ directory, so there is a record to read before you pull.

The licence is MIT, declared in both the README and package.json. MIT permits use, modification and redistribution with the licence and copyright notice retained. That is permissive enough for the plugin and skills.sh paths as described. This is a description of the licence text, not legal advice; if you are redistributing the skills inside a commercial product, have your own counsel read the terms.

Editorial conclusion

Adopt mattpocock/skills if you already run a coding agent on a real repository and want a lightweight, MIT licensed set of prompts you can read and edit, rather than a framework that owns your process. Skip it if you want a tool that enforces a workflow for you, or if you expect the skills to work without running /setup-matt-pocock-skills first. Before committing, verify which install path you are on, because the Claude Code plugin is read-only and updates automatically while the skills.sh installer writes editable files into your repo, and running both leaves every skill duplicated. Then open skills/productivity/grill-me/SKILL.md and read it before you run it.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes