Why TypeScript Guru Matt Pocock’s New AI Skills Reject Vibe Coding

Repository Overview

Matt Pocock released the open‑source repository mattpocock/skills with the subtitle “Skills For Real Engineers”, targeting real development work rather than “vibe coding”.

Why “Skills” Instead of BMAD, Spec‑Kit, or GSD?

Frameworks such as BMAD, Spec‑Kit, and GSD define a complete, black‑box workflow for AI‑assisted coding, which can remove developer control and make debugging intermediate steps difficult. “Skills” are tiny, easily editable, composable fragments that do not bind to a specific model—both Claude Code and Codex can run them. The design draws on decades of engineering practice rather than novel AI‑only techniques.

30‑Second Installation

npx skills@latest add mattpocock/skills

After installation the required initializer /setup-matt-pocock-skills asks three questions to establish repository context:

Issue tracker choice (GitHub, Linear, or local markdown).

Label set for triage (default: needs-triage, ready-for-agent, etc.).

Directory for generated documentation.

Four AI‑Coding Ailments and Corresponding Skills

Ailment 1: AI Doesn’t Do What You Want

Typical failure: the developer intends outcome A, describes B, the AI interprets C, and produces D. Matt references a line from *The Pragmatic Programmer*: “No one knows exactly what they want.”

Solution: the “Grilling Session” where the AI interrogates the developer until a shared understanding is reached. Implemented by two Skills: /grill-me: the agent asks follow‑up questions like an interviewer, continuing until explicit answers are given for each design branch. /grill-with-docs: same as /grill-me but also compares answers against the project’s CONTEXT.md to surface terminology conflicts.

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies one‑by‑one. For each question, provide your recommended answer. Ask the questions one at a time.

Ailment 2: AI Is Verbose and Burns Tokens

Matt cites Eric Evans’s *Domain‑Driven Design*: developers and domain experts initially speak different languages, and AI behaves similarly, spending many tokens inferring project‑specific jargon.

Example from the course-video-manager project: a long description of “the problem that occurs when a lesson is assigned a real filesystem location” was abbreviated to the term materialization cascade in CONTEXT.md. After that, “materialization cascade bug” conveys the issue with far fewer tokens.

Benefits of a shared vocabulary include consistent naming, easier code‑base navigation for the agent, and reduced token consumption. The /grill-with-docs Skill records new terms in CONTEXT.md and architectural decisions in docs/adr/. ADRs are written only when all three criteria are met: the decision is hard to reverse, future readers would wonder “why this was done”, and a genuine trade‑off was evaluated.

Ailment 3: Generated Code Is Simply Wrong

Even with aligned requirements, AI can produce buggy code. Matt’s remedy is the classic Test‑Driven Development (TDD) red‑green‑refactor loop, exposed as the /tdd Skill.

He warns against the “horizontal slice” anti‑pattern (writing all tests first, then all implementations), which yields “garbage tests”. The preferred “vertical slice” approach writes one test, implements the minimal code to pass it, then proceeds to the next test.

错误（水平）:
  RED:   test1, test2, test3, test4, test5
  GREEN: impl1, impl2, impl3, impl4, impl5

正确（垂直）:
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  ...

Another Skill, /diagnose, breaks debugging into six phases, emphasizing Phase 1: a fast, deterministic pass/fail signal that the agent can run. The priority order for failure signals is:

Failing tests

Curl scripts

CLI calls

Headless browsers

Traffic replay

One‑off harnesses

Fuzz testing

Git bisect

Manual clicks (last resort)

Ailment 4: Project Devolves into Architectural Decay

Rapid AI‑generated code can cause the codebase to become tangled. Matt proposes three Skills to re‑emphasize design: /to-prd: converts the current conversation into a Product Requirements Document, first asking which modules will change. /zoom-out: provides a map of related modules and callers, helping the agent step back from a single file. /improve-codebase-architecture: searches the existing code for “deepening opportunities”.

He references John Ousterhout’s *Software Design Philosophy*: “Good modules are deep; complex functionality hides behind simple interfaces.” This is operationalized as a “delete‑test”: imagine deleting a module—if complexity disappears, the module is a thin façade; if complexity spreads to many callers, the module performs substantive work. The /improve-codebase-architecture Skill is recommended to run every few days.

Additional Handy Tools

/caveman

: “caveman mode” strips filler words, saving up to 75 % of tokens.

普通模式:
"Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."

穴居人模式:
"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"

/git-guardrails-claude-code

: adds a PreToolUse hook for Claude Code that blocks dangerous git commands such as git push (including --force), git reset --hard, git clean -f, git branch -D, git checkout ., and git restore .. When blocked, the AI asks for confirmation before proceeding. /write-a-skill: scaffolds a new Skill, guiding the author to produce a compliant SKILL.md with required trigger keywords. /triage: implements a five‑state issue workflow (needs‑triage, needs‑info, ready‑for‑agent, ready‑for‑human, wontfix) and prefixes AI‑generated comments with > *This was generated by AI during triage.* to avoid confusion.

Repository URL

https://github.com/mattpocock/skills