Matt Pocock's AI Skills: 238K Stars, 18M Installs - Engineering Discipline for LLMs

The author opens with a common frustration when using AI to write code: requirements seem clear, the model responds quickly, but the output misses the mark. Reviewing their own rework history, they find the root cause is rarely model intelligence—it's the missing "rules of engagement" between human and AI: requirements not probed deeply, results not verified.

What the Repository Is

Matt Pocock, author of Total TypeScript and former engineer at Vercel and Stately, open-sourced the .agents directory he uses daily as the repository mattpocock/skills. It holds 53 skills on skills.sh ( https://skills.sh), 238K stars, 20K+ forks, MIT license, and over 18 million cumulative installs—the highest-install skill set available.

A skill is a folder containing a markdown file that tells an AI how to execute a specific class of task. Invoked by commands like /tdd, skills load only for the triggering session, unlike CLAUDE.md which loads every time. This keeps context lean.

The project differs from Spec Kit or BMAD: those aim to let process drive everything; Pocock's skills are small, single-purpose, and the developer decides which to use and when.

Skills Grouped by Workflow Phase

1. Before Coding: Clarify Requirements

/grill-me

(900K+ installs) and /grill-with-docs are the most popular. They make the AI interrogate the user before any code is written—one focused question at a time—until every ambiguity is resolved. The author reports frequently being stumped, revealing assumptions they hadn't recognized. /grill-with-docs adds two artifacts: a CONTEXT.md that normalizes project terminology (e.g., replacing a long description with the single term "materialization cascade"), and ADR (Architecture Decision Record) files for irreversible technical decisions. Once defined, the AI consistently uses the agreed vocabulary in variable names, file names, and code. /ask-matt helps pick the right skill when the catalog feels overwhelming.

2. During Coding: Test-Driven Development & Bug Diagnosis

/tdd

enforces genuine test-driven development: write one failing test, write the minimal implementation to pass, repeat. It explicitly blocks the common "fake TDD" pattern of writing all tests up front then all implementations, which tests imagined behavior rather than real behavior. /diagnosing-bugs imposes a hard rule: a stable reproduction command must be crafted and executed before any hypothesis generation . If you can't reproduce it, you're not allowed to guess. The author suggests adopting this rule directly into team bug templates. /code-review runs two independent passes: one for project-style conformance, one for requirement fulfillment—neither interferes with the other.

3. Codebase Health: Architecture Guardrails

/improve-codebase-architecture

scans the entire repo, identifies modules worth cleaning up, and emits an HTML report listing candidates. The developer picks one; the skill then discusses how to refactor it. It does not auto-refactor. The author runs it every few days.

Its theoretical basis is the classic "deep vs. shallow modules" distinction: shallow modules have interfaces as complex as their implementations (mere pass-throughs) and are the primary targets for cleanup.

4. End-to-End Workflow Orchestration

These skills chain the single-purpose ones into a full lifecycle: /to-spec — consolidates the current conversation into a spec document and pushes it to the issue tracker; no new questions. /to-tickets — breaks the spec into ordered, dependency-aware tickets. /implement — executes tickets, automatically invoking /tdd rhythm and finishing with /code-review. /triage — processes incoming issues through a defined state machine. /handoff — compresses a long, stale session into a handoff document so a fresh session (or another tool) can continue without context loss. /prototype — builds a throwaway prototype for "must-see-to-understand" problems; the skill forbids committing prototype code to the repo.

Installation

Two paths, pick one: claude plugins install mattpocock-skills Installs as a read-only subscription from the official plugin market; updates auto-sync. npx skills@latest add mattpocock/skills Copies skill files into the project for local modification. Running both duplicates skills.

After install, run /setup-matt-pocock-skills once per repository to configure issue location, triage labels, and docs directory—other skills need these paths to write artifacts.

The README states work with any model; skills can be targeted at Codex or any Agent Skills–compatible client.

When to Use (and Not Use)

New, fuzzy requirements — /grill-me pays off; the half-hour interrogation beats days of rework.

Bugs that won't reproduce — /diagnosing-bugs forces the reproduction step that is often skipped.

Legacy codebases growing messy — periodic /improve-codebase-architecture runs surface cleanup candidates.

Non-coding decisions — /grill-me works for design docs, product ideas, architectural choices.

Not suited for quick demos, throwaway scripts, or "vibe coding"; the overhead isn't justified. The README explicitly notes these skills are for real engineering.

Author's Takeaways

Nothing in the repository is new—requirement interrogation, TDD, ubiquitous language, ADRs, prototype validation are decades-old software engineering wisdom. The contribution is encoding them as AI-executable files . As AI writes code faster, classic failure modes (unclear requirements, architectural decay) amplify; the old guardrails become essential again.

The design keeps judgment human: every skill is plain text in the repo, forkable and editable. No black-box framework makes decisions for you. The author recommends starting with /grill-with-docs as the entry point, then adding others as needed.

https://github.com/mattpocock/skills