I went looking into Matt Pocock’s skills repo for a specific reason: it turns out I already have it installed. It ships as a Claude Code plugin, and at some point I must have added it without thinking too hard about what was in it. So this started as “wait, what is this thing actually doing” and turned into a much longer read than I expected.

Quick context if you haven’t run into this: Matt Pocock is the TypeScript educator behind Total TypeScript, and last spring he made his personal .claude directory public as mattpocock/skills. It’s a set of small markdown files, each one an instruction packet for an AI coding agent, covering things like test-driven development, bug diagnosis, code review, and turning a vague idea into a shippable spec. It went from a few hundred stars to deep into six figures within about a week, and it’s still growing.

One honest warning before I get into it: half of what comes up when you search this repo’s name is SEO content-mill slop. I found at least six nearly-identical blog posts (tosea.ai, knightli.com, explainx.ai, agentpedia.codes, and a few more) that all say roughly the same three sentences about it in slightly different order, several citing wildly different star counts for the same week. Given my day job is literally tracking AI-driven changes to the labor market, that’s a fun little proof of concept I didn’t go looking for. Everything below is pulled from the actual SKILL.md files in the repo, the real GitHub issues filed against it, and two Hacker News threads, not the blogspam.

Design rationale: underspecification and missing ubiquitous language

Pocock’s own README frames it around two failure modes, and both are worth stating plainly because they’re the whole design rationale:

Failure mode one: the agent didn’t build what you wanted. He quotes The Pragmatic Programmer’s “no-one knows exactly what they want” and treats this as a communication gap, not a model capability gap. The fix is what he calls a grilling session: before any code gets written, the agent interviews you, one question at a time, walking down a decision tree until every branch is resolved.

Failure mode two: the agent is too verbose, because it doesn’t share your project’s vocabulary. He borrows Eric Evans’ “ubiquitous language” from Domain-Driven Design here: a CONTEXT.md glossary the agent reads before doing anything, so it says “Order” instead of a paragraph describing what an Order is every time.

Both are real problems, and neither is unique to Pocock’s approach. What’s distinctive is that he explicitly positions this against heavier “own your whole process” frameworks (he names GSD, BMAD, and Spec-Kit) and picks the opposite bet: small, readable, individually editable files instead of one framework that takes the wheel. That’s a genuine design tradeoff, not a neutral default, and it’s worth sitting with for a second before you adopt it: a heavier framework gives a beginner more guardrails; a pile of small skills gives an experienced engineer more control and more assembly work.

Core workflow: grill → prototype → spec → tickets → implement → review

Once you clear away the marketing, there’s a real flow here, and it’s worth drawing because none of the SEO posts draw it correctly.

The main flow, idea to shipped code:

  1. /grill-with-docs interviews you about what you’re building and writes what it learns into CONTEXT.md and architecture decision records as it goes. (/grill-me is the same interview stripped of the codebase-writing side, for when you don’t have a repo yet.)
  2. If a question needs a runnable answer instead of a conversation, you detour into /prototype, a deliberately throwaway program that answers exactly one design question and nothing else.
  3. For anything bigger than one session, /to-spec turns the conversation into a proper spec (problem statement, user stories, the works), then /to-tickets slices that spec into what Pocock calls tracer-bullet tickets: narrow vertical cuts through every layer, each one declaring which other tickets block it.
  4. /implement picks up a ticket and drives /tdd internally (strict red-green-refactor, one behavior at a time, tests only at pre-agreed seams), then closes out with /code-review, which runs two review passes in parallel subagents: one checking the diff against your documented coding standards, one checking it against the original spec. It reports both separately on purpose, because code that passes one axis often fails the other.

Three on-ramps feed into that flow from the side: /triage for bug reports and feature requests that arrive raw and need sorting into a state machine before an agent should touch them; /diagnosing-bugs for anything that resists a first-glance fix; and /wayfinder, which is the heaviest tool in the box, for work so large and foggy you can’t even scope it into tickets yet.

The /diagnosing-bugs skill is honestly the best-written thing in the whole repo. Its entire thesis is: build a tight, deterministic, fast feedback loop that can go red on this specific bug before you’re allowed to theorize about the cause. If you catch yourself reading code to form a hypothesis before that loop exists, the skill explicitly calls that out as the exact failure it’s designed to prevent. That’s a genuinely good discipline whether or not you ever install a single one of these skills.

Meta-skill: writing-great-skills and agent prompt design

Buried in the productivity folder is a skill called writing-great-skills, and it’s the most interesting document in the entire repo. It’s Pocock’s own theory of how to write instructions for an LLM agent, and it’s more rigorous than most public writing on prompt engineering I’ve seen. A few ideas worth stealing even if you never touch his TDD workflow:

  • Model-invoked vs. user-invoked skills is a real cost tradeoff. A model-invoked skill’s description sits in the context window on every single turn, whether you use it or not. A user-invoked skill costs zero context but means you have to remember it exists. He’s explicit that you should only make something model-invoked if the agent genuinely needs to reach for it on its own.
  • “Leading words.” A leading word is a short, already-meaningful term (his examples: tight, red, tracer bullet) that compresses a whole paragraph of restated behavior into one token the model already has priors about. “Fast, deterministic, low-overhead” becomes “tight.” It’s a real technique, not just cute naming.
  • The no-op test. For every sentence in a prompt, ask: does this actually change behavior versus what the model would already do by default? If not, delete it, it’s just burning tokens to say nothing.
  • Negation backfires. Telling a model what not to do names the exact thing you didn’t want, the same way “don’t think of an elephant” doesn’t work on people either. State the positive target instead.

If you’re writing your own Claude Code skills, CLAUDE.md files, or system prompts for anything, this document is worth reading on its own regardless of whether you ever install the rest of the repo.

Critiques: self-report bias, skill reliability, stack lock-in, and MCP

This is the part the SEO posts skip entirely, because it requires reading past the launch-week hype.

The self-referential trust problem. On the Hacker News thread about why grill-me went viral, the sharpest pushback wasn’t about any specific skill, it was structural: several commenters pointed out there’s no strong reason to trust an LLM’s own account of what makes it perform better. Phrasing like “walk down each branch of the decision tree” sounds more rigorous than just saying “be critical” or “ask me clarifying questions,” but nobody in that thread had run a controlled comparison showing the elaborate phrasing actually produces a different outcome versus the plain version. That’s a fair challenge to sit with. I don’t think it means the skill is useless, structured prompts do seem to help in my own experience, but “sounds more sophisticated” and “is more effective” are different claims, and it’s worth staying honest about which one you actually have evidence for.

Real, filed rough edges. A look through the repo’s GitHub issues turns up specific, credible complaints, not vague grumbling: the TDD skill has been flagged for causing “attention dilution” in longer sessions and needs restructuring into cleaner phases. The code-review skill’s two subagents are trusted at face value rather than having their findings independently verified. There’s an open request for an explain-diff skill, because right now nothing in the set helps you understand code the agent already wrote for you. And grill-me itself has a filed issue (#527) noting it’s scoped only to plans and designs, when people clearly want the same relentless-interview treatment for opinions and arguments that have nothing to do with a build.

Stack lock-in, though this one’s genuinely improving. The original complaint, and it was a fair one, was that the whole set assumed a TypeScript/Node world with GitHub issues and Husky hooks. migrate-to-shoehorn is completely useless unless you happen to use Pocock’s own TypeScript testing library. But the changelog shows real movement here: setup-matt-pocock-skills now supports a local-markdown issue tracker and GitLab alongside GitHub, and it skips asking about triage labels entirely if you haven’t installed the triage skill. That’s the project responding to real feedback rather than ignoring it, which counts for something.

The MCP-vs-skills debate is bigger than this repo, but it applies here. A separate Hacker News thread on preferring MCP over skills makes the case that markdown-file skills don’t compose the way a proper tool protocol does, and that large tool descriptions eat your context budget for no good reason. The fair rebuttal is that skills are just documentation, so they cost nothing extra when unused (see the model-invoked/user-invoked split above), and a CLI-plus-skills setup is a lot more transparent than a black-box server. Neither side is wrong; it depends on whether you’re building a persistent product or driving your own local agent loop.

It’s still literally his dotfiles. There’s a personal folder in there with skills for editing his own newsletter articles and managing his own Obsidian vault. Nobody needs those. The README says “hack around, make them your own,” and I’d take that literally: the plugin install gives you the whole bundle as read-only, but the honest move is to look at what’s actually in skills/engineering and skills/productivity and cherry-pick, not install all 39 and hope for the best.

Adoption practices: setup, curation, context budget, and feedback loops

  • Run /setup-matt-pocock-skills before anything else. It asks three questions (issue tracker, triage labels, doc layout) and writes the answers to files every other skill reads from. Skip it and half the skills will just ask you where things live, over and over.
  • Curate instead of installing everything. Decide if you want the plugin (read-only, auto-updating, good if you just want to follow along) or the skills.sh install (copies editable files into your repo, good if you’re going to change them). Then actually open the folders and drop the ones you’ll never use, especially anything in misc or personal that’s tied to his specific tooling.
  • Respect the context window during the main flow. Pocock calls the usable reasoning window before a model degrades the “smart zone,” roughly 120k tokens on current frontier models. His own guidance is to keep grilling, spec-writing, and ticket-splitting in one unbroken session, then start /implement fresh per ticket. If a planning session is creeping toward that limit, use /handoff rather than pushing on a degraded context.
  • Don’t skip the feedback-loop discipline in /diagnosing-bugs, even if you never touch another skill in the set. Build the thing that goes red on your specific bug before you let yourself (or the agent) theorize about the cause.
  • Treat prototypes as evidence, not scratch work. The current version of /prototype commits throwaway code to its own branch with a pointer back to the ticket, rather than deleting it. If you’re doing exploratory spikes by hand, steal this habit regardless of whether you use the skill.
  • If you write your own skills, read writing-great-skills first. It’ll save you from padding every prompt with restated qualifiers that the model already does by default.

Assessment: transferable discipline vs. unvalidated phrasing

The genuinely good part of this repo isn’t any single skill, it’s that Pocock is applying actual software engineering discipline (seams, tracer bullets, red-green-refactor, two-axis review) to the specific problem of directing an agent that doesn’t share your context. That’s a real contribution and worth learning from even if you write your own version instead of installing his.

The part I’d push back on is the same part Hacker News pushed back on: some of this is genuinely load-bearing structure, and some of it is confident phrasing that hasn’t been shown to outperform plainer instructions. The repo doesn’t make it easy to tell which parts are which, and neither does most of the coverage of it. Given how much of that coverage turned out to be AI-generated filler restating the README, I’d trust your own week of usage over any blog post about it, including honestly, this one.

Sources I actually read for this, rather than took secondhand: the mattpocock/skills repo and its issues, aihero.dev/skills, and the Hacker News threads on grill-me and MCP vs. skills.