How 6 Skills from Matt Pocock Teach AI to Match Real Engineer Discipline

Matt Pocock’s Skills For Real Engineers repository (README lines 11‑19) presents a collection of agent skills aimed at restoring software‑engineering discipline to AI‑assisted coding. The README emphasizes that the core message is “Software engineering fundamentals matter more than ever” (README.md:165‑167).

Agent failure modes

Intent misalignment : developers assume requirements are clear, but the agent misinterprets them.

Language bloat : without a shared vocabulary, the agent resorts to verbose descriptions.

Code cannot work : the agent lacks a feedback loop that observes real execution results.

Code becomes a ball of mud : rapid code generation accelerates software entropy.

Each skill encodes a non‑skippable gate that blocks progress when a failure pattern is detected.

1. writing‑great‑skills

Location: skills/productivity/writing-great-skills/ (not in the engineering bucket).

This meta‑skill defines a skill’s purpose as “wrangling determinism out of a stochastic system”. The goal is not identical output on every run, but identical process (Predictability is the primary quality, see GLOSSARY.md:9‑13).

Key concept: Leading word – a compact pre‑trained model concept that anchors execution with few tokens (writing‑great‑skills/SKILL.md:61‑72; GLOSSARY.md:129‑135). Examples:

Fold “fast, deterministic, low‑overhead” into the word tight .

Fold “a loop you believe in” into the word red .

Failure modes (SKILL.md:74‑83; GLOSSARY.md:155‑201):

Premature completion : moving to the next step before the current one truly finishes.

No‑op : issuing a command that does not change the model’s default behavior.

Actionable step: replace vague checklist items (e.g., “thorough investigation”, “keep tests stable”) with a leading word and a concrete completion criterion.

2. codebase‑design

Location: skills/engineering/codebase-design/

Focuses on two core terms: deep module and seam .

Depth : a deep module provides large behavior through a small interface (codebase-design/SKILL.md:14‑20).

Seam (Michael Feathers): a place where behavior can be changed without editing the code directly; the seam is the interface location (codebase-design/SKILL.md:20‑24).

Leverage for callers and locality for maintainers (codebase-design/SKILL.md:24‑28).

Failure modes:

Shallow module : interface and implementation are equally complex (codebase-design/SKILL.md:30‑52).

Hypothetical seam : a single adapter indicates a hypothetical seam; two adapters indicate a real seam (codebase-design/SKILL.md:60‑65).

Actionable step: run a “deletion test” on a frequently changed module; if removing the module collapses complexity, the module is deep, otherwise it is shallow.

3. tdd

Location: skills/engineering/tdd/

The skill narrows TDD to a single action: the red → green loop , requiring tests to verify only the public interface, not implementation details (tdd/SKILL.md:6‑16).

Core terms:

Pre‑agreed seam : write the seam to be tested before writing the test, avoiding wasted test budget (tdd/SKILL.md:18‑24).

Tracer bullet : each test is a minimal implementation that feeds learned knowledge into the next iteration (tdd/SKILL.md:26‑35).

Failure modes:

Implementation‑coupled : mocking internal collaborators or testing private methods causes tests to break on refactor (tdd/SKILL.md:26‑29).

Tautological : asserting the same method used to compute the expectation (tdd/SKILL.md:28‑30).

Horizontal slicing : writing all tests before any implementation leads to testing imagined shapes rather than real behavior (tdd/SKILL.md:29‑30).

Actionable step: before a new feature, write a single sentence—“What is the public interface? Which seam are we confirming?”—then perform one red‑to‑green iteration and forbid predicting future requirements.

4. diagnosing‑bugs

Location: skills/engineering/diagnosing-bugs/

The skill’s mantra is “The tight loop is the skill”. A bug must first produce a red‑capable command that is deterministic, fast, and runnable by the agent (diagnosing-bugs/SKILL.md:12‑16; 47‑60).

Failure modes:

Jumping straight to a hypothesis : attempting a hypothesis before a red‑capable command exists (diagnosing-bugs/SKILL.md:51‑60).

Single‑hypothesis anchoring : generating only one hypothesis anchors the investigation (diagnosing-bugs/SKILL.md:82‑92).

Wrong bug = wrong fix : the feedback loop captures a nearby failure rather than the reported symptom (diagnosing-bugs/SKILL.md:62‑80).

Actionable step: add a “One command:” field at the top of every bug issue containing a minimal test, curl, CLI command, or harness that reproduces the symptom; if no command exists, prohibit speculative root‑cause guesses.

5. improve‑codebase‑architecture

Location: skills/engineering/improve-codebase-architecture/

This skill reuses the strict vocabulary of codebase‑design to turn shallow modules into deep ones, creating a deepening opportunity aimed at testability and AI‑navigability (improve-codebase-architecture/SKILL.md:7‑14).

Failure modes:

Rigid heuristics : avoid static rules; instead organically explore (improve-codebase-architecture/SKILL.md:27‑35).

Premature interface design : present candidates, problem, and benefit before committing to an interface (improve-codebase-architecture/SKILL.md:37‑64).

Generic architecture language : reports must tie every benefit back to locality/leverage, rejecting vague terms like “cleaner code” (HTML-REPORT.md:106‑123).

Actionable step: from the last 20‑50 commits, pick a frequently changed region, create a “deepening candidate” card (Files, Problem, Solution, Locality/Leverage, Before/After) and let the team vote on its priority before refactoring.

6. prototype

Location: skills/engineering/prototype/

Prototype is defined narrowly as “throwaway code that answers a question” (prototype/SKILL.md:6‑15). The question determines the shape; UI problems require multiple divergent variants (prototype/SKILL.md:10‑17).

Failure modes:

Throwaway code becomes production code : do not mark the code as throwaway, avoid tests, error handling, or abstraction (prototype/SKILL.md:19‑25).

Question/branch mismatch : selecting the wrong logical or UI artifact because the question was not clarified first.

Actionable step: at the top of a prototype directory or issue, add two lines:

Question: What does this prototype answer?
Run: Which command starts it?

After validation, merge the decision into the main codebase and keep the prototype on a throwaway branch.

Common patterns across the six skills

1. Use explicit completion criteria (gates) instead of vague adjectives.

2. Compress decision space with shared leading words such as tight, red, tracer bullet, seam, and deepening opportunity.

3. Embed failure modes directly into workflows, turning “we should …” into triggerable conditions.

4. Preserve human control: pre‑agreed seams, red‑capable commands, candidate‑first architecture reviews, and explicit model‑vs‑user invocation choices.

Three quick actions to try before leaving work

Add a “One command:” line to bug‑issue templates (from diagnosing‑bugs) to force a reproducible red‑capable command.

Select a frequently changed module from the last 20‑50 commits and run a deletion test (from codebase‑design & improve‑codebase‑architecture).

In PR or demo docs, add “Question:” and “Run:” lines (from prototype) to ensure every prototype has a clear purpose and launch command.

These actions require no new tooling, only the adoption of the minimal executable units—words, gates, and actions—defined in the six skills.