270k Stars, 27 Markdown Files: Baking Engineering Discipline Into AI Coding Assistants

What It Is

The mattpocock/skills repository (275.7k stars, 23.1k forks, MIT license) solves a common frustration: AI coding assistants are powerful but forget your rules between sessions. You say "write tests first" and it complies once, then reverts to old habits. Author Matt Pocock (creator of Total TypeScript) packages 27 skill files — plain Markdown, no code — that become two things inside your assistant:

Slash commands : you invoke explicitly, e.g. /grill-me Behavioral rules : the assistant auto-invokes when context matches, e.g. tdd triggers test-first flow during coding

The content encodes engineering decision rules , not language- or framework-specific syntax.

Key Skills

/grill-me (manual): Forces the assistant to recursively question your requirements until every decision is explicit

/tdd (auto / manual): Enforces red-green loop; defines three anti-patterns: implementation-coupled tests, tautological tests ( expect(add(a,b)).toBe(a+b)), and horizontal slicing (all tests then all code)

/code-review (manual): Dual-axis review: one axis checks repo conventions (falls back to Fowler's code smells), the other verifies the change matches the original ticket; run by parallel sub-agents

/improve-codebase-architecture (manual): Scans the codebase, identifies refactor candidates, produces a visual report

/diagnosing-bugs (auto): Structured debugging: reproduce → minimize → hypothesize → instrument → fix → add regression test

Organization: Two Layers

27 skills split into Engineering (20, code-focused) and Productivity (7, general workflow). A design intent separates orchestration layer (manual-only: grill-me, triage, wayfinder) from discipline layer (auto-invokable: tdd, grilling, codebase-design). Hard rule: orchestration may call discipline; orchestration never calls orchestration.

End-to-End Scenario: Adding a Feature

/grill-me

— Assistant builds a decision tree. Each round it asks only questions whose preconditions are settled, numbering each and offering a recommended answer. Example:

❓ Q1 - Data store: local SQLite or existing Postgres? ➡️ Reuse Postgres, pool exists
❓ Q2 - Cache layer? ➡️ Skip for now, add after feature works
❓ Q3 - Retry strategy? ➡️ Exponential backoff, max 3

Assistant fetches facts (reads files, searches code); you make decisions. Continues until no "silent assumptions" remain. /to-spec — Compiles the dialogue into a spec pushed to your tracker (GitHub Issues, Linear, or local file). /to-tickets — Breaks spec into executable tickets with declared dependencies. /implement — Assistant works tickets vertically; coding auto-runs /tdd (test first), finishes a slice, then /code-review gates commit.

The system manages decision points , not code style.

Deep Dives

/tdd: Defining Bad Tests

Three anti-patterns:

Implementation-coupled tests : break when internals change but behavior is stable — blocks refactoring

Tautological tests : expect(add(a,b)).toBe(a+b) — verifies code with its own logic, never fails

Horizontal slicing : write all tests upfront, then all implementation — validates imagined behavior

Introduces seams : tests target only pre-agreed public boundaries; list seams before writing. Budget tests on critical paths and complex logic.

/code-review: Two Independent Axes

Axis 1: style/convention compliance (repo rules or Fowler baseline). Axis 2: fidelity to the original ticket. Parallel sub-agents avoid context pollution; results merged at the end. Rationale: mixing "code quality" and "requirement adherence" lets both slip.

/grill-with-docs: Living Glossary

During questioning, builds GLOSSARY.md — each term's meaning, relations, and explicitly forbidden synonyms. Example: repo banned "backlog" (ambiguous: tool vs. collection), split into "Issue tracker" and "Issue". Consistent naming reduces assistant confusion and token spend.

Installation: Two Paths

Path 1 — Claude Code official plugin (read-only, auto-updates): claude plugins install mattpocock-skills Path 2 — skills.sh universal installer (copies files into your project, fully editable): npx skills@latest add mattpocock/skills Pick one; both creates duplicates. Then run /setup-matt-pocock-skills to configure: ticket destination (GitHub Issues / Linear / local), triage labels, doc storage.

Who Should (and Shouldn't) Use It

Fit : daily AI-assisted work on real codebases with backlogs and schedules. If you've suffered "assistant built something different from what I asked," /grill-me alone may justify adoption.

Not fit : throwaway scripts or weekend demos. The discipline adds overhead — half-hour questioning, test-first, pre-commit review — that pays off only in long-lived code.

Hidden gate : you must care about design. Skills codify your judgment for repeat execution; no judgment to codify means extra process without value.

Contrast with GSD, BMAD, Spec-Kit: those frameworks hand the entire flow to the assistant, creating a black box. mattpocock/skills stays small, inspectable (each file ~10 min read), and composable — swap or edit any skill.

Impact signal: /grill-me alone exceeds 1.3 million installs via skills.sh.

GitHub:

github.com/mattpocock/skills