27 Agent Skills That Gate Every Stage of AI-Driven Development

The article introduces an open-source collection of 27 agent skills authored by Matt Pocock (Total TypeScript) under the motto "real engineering, not vibe coding." The core insight: each skill defines a concrete exit criterion for a specific development stage, giving AI agents hard boundaries instead of vague instructions.

Four Failure Modes of AI Coding

The README categorizes AI coding failures into four types, each paired with a classic software-engineering quote and a matching skill:

Alignment failure — "Nobody knows exactly what they want" ( The Pragmatic Programmer ). Solved by grill-me and grill-with-docs, where the agent interrogates the user until consensus is reached.

Verbosity — Agents invent jargon; Evans' Domain-Driven Design prescribes a ubiquitous language. The skill GLOSSARY.md captures shared vocabulary once per project. Example: a verbose phrase "课程里某一节的内容变成真实文件" compresses to the single term 物化级联 (materialization cascade).

Code that doesn't work — Without a feedback loop the agent flies blind. "Feedback speed is your speed limit" ( The Pragmatic Programmer ). Addressed by tdd (red-green loop) and diagnosing-bugs.

Big ball of mud — Accelerated entropy. Kent Beck's daily design investment and Ousterhout's deep modules (lots of behavior behind small interfaces) are baked into every layer.

Panoramic Map: One Main Line, Three Entry Points

The router skill ask-matt organizes the 27 skills into:

Main line : idea → ship, eight sequential activities.

Three entry points : triage (external tickets), diagnosing-bugs (hard bugs), wayfinder (foggy requirements) — all merge back to the main line.

Debt channel : improve-codebase-architecture runs opportunistically.

Vocabulary floor : domain-modeling and codebase-design define shared design terms.

Requirements Line: Eight Activities with Exit Criteria

Each activity has a skill, artifact, and exit condition:

Requirement clarification — Skill: grill-with-docs. Artifact: GLOSSARY terms, ADR records. Exit: Design-tree frontier empty, no hidden assumptions, user confirms consensus.

Branch judgment — Skill: prototype / wayfinder. Artifact: Throwaway prototype or decision-ticket map. Exit: Question answered or fog cleared; conclusion fed back to main line.

Solution design — Skill: to-spec. Artifact: Seven-section spec. Exit: Published to tracker with ready-for-agent label.

Task breakdown — Skill: to-tickets. Artifact: Vertical-slice tickets + blocking edges. Exit: User approves granularity and dependencies.

Coding & testing — Skill: implement + tdd. Artifact: Red-green loop output (code + tests). Exit: Full test suite passes, code-review complete.

Review — Skill: code-review. Artifact: Dual-axis report. Exit: Standards axis and Spec axis each produce a conclusion.

Delivery — Skill: pr. Artifact: Three-section PR description. Exit: Summary, evidence, merge-risk all present.

Retrospective — Skill: retro. Artifact: Environment-improvement candidates. Exit: Sorted by severity and presented to user.

Key Activity Details

Clarification uses a design tree: each decision branches into sub-decisions. Only the current frontier (questions whose prerequisites are settled) is asked per round. Agent researches facts; human makes decisions. Exit: frontier empty, no silent assumptions, explicit consensus.

Branch judgment has two flavors: handoff spins a throwaway prototype for concrete questions (state-machine correctness, UI look); wayfinder maps a foggy epic into decision tickets, solves one ticket per session, emits decisions only, then merges into to-spec.

Solution design is deliberately conservative: no re-interviewing, only synthesis. Mandatory step — draw the test seam(s) and confirm with user; fewer seams is better (ideal = one). Non-goals section explicitly states what is out of scope. Spec gets ready-for-agent label to skip triage.

Task breakdown produces tracer-bullet vertical slices: each ticket is narrow, end-to-end demonstrable, and fits in a fresh context window. Large refactors follow expand-migrate-contract: run old and new side-by-side, migrate incrementally, then delete old.

Coding is deliberately minimal: implement picks a ticket, drives TDD at the agreed seam, runs type checks and unit tests continuously, finishes with code-review, commits. One ticket = one clean session. Refactoring is explicitly excluded from the red-green loop and deferred to review. For large specs, implement-spec treats tickets as a task graph and spawns parallel sub-agents in separate worktrees.

Review runs two parallel sub-agents: Standards axis (repo conventions + 12 Fowler code-smell baselines) and Spec axis (faithfulness to spec). Reports stay separate — code can be clean but solve the wrong problem.

Delivery PR has exactly three sections: minimal visual summary (pseudocode, call tree, or file tree — whichever is smallest), before/after evidence (screenshots = S-tier, test output = A-tier), merge risk (one-way vs two-way door, blast radius in one word).

Retrospective closes the loop by improving the environment, not the code. Seven categories (navigation pointers, automated checks, coding standards, tool overhead, etc.) are scanned. Mechanical errors become deterministic checks; judgment calls become coding standards. Next build starts from a better environment.

Bug Line: Build a Red Loop First

External reports enter triage: two buckets (bug vs enhancement) plus a five-state role state machine that normalizes messy intake into an agent-ready brief. Two telling details: every AI comment in triage carries a disclaimer; external PRs are treated as "issues with code" and fed through the same machine.

The discipline core is diagnosing-bugs. Phase one has a single job: create a feedback loop that turns red for this specific bug . The skill lists ten techniques in order: failing test, curl script, request replay, property-based fuzz, git bisect automation script, etc. Acceptance is strict: one command, already run once, reproduces original symptom in seconds, no human babysitting. No hypotheses allowed until the loop is red.

After fix, same-session retro hunts root cause. If no suitable seam exists to pin the bug with a regression test, that itself is a finding: architecture prevents nailing the bug — route to improve-codebase-architecture.

Getting Started in Three Steps

Install skill pack. Claude Code: claude plugin install; others: npx skills add mattpocock/skills (include setup-matt-pocock-skills).

Per repository, run /setup-matt-pocock-skills to configure issue tracker, triage label mapping, docs location.

Start using. Human-invoked user-invoked skills orchestrate (e.g., /to-spec); agent-invoked model-invoked skills enforce discipline (e.g., tdd). One orchestrates, one disciplines — no crossing.

The framework treats not model capability but process boundaries. Across 27 files the same sentence recurs: how far must this step go before it counts as done?