mattpocock-skills prunes by three tests, and keeps Fowler's smells out of codebase-design

Introduction

I watched a video about Matt Pocock’s mattpocock-skills plugin, built around a skill called grill-me that the video described as five lines of instruction forcing an agent to interrogate you about a plan before it will write any code. This repo already had the plugin installed from an earlier session, and I wanted to understand the actual discipline behind that terseness rather than repeat the video’s summary of it, so I asked for an honest audit: were we actually using mattpocock-skills, or had it just been configured and left dormant. Reading the plugin’s own source corrected two of the video’s specific claims before either was repeated anywhere: grill-me is a seven-line wrapper around a twenty-eight-line primitive, and the Fowler Refactoring code smells live in a different skill than the one most people would guess, and applying the discipline for real, not just reading about it, caught a genuine bug in our own review pipeline the same session it was added. This article walks through what the plugin’s own meta-skill, writing-for-agents, actually says about pruning and dense vocabulary, then the two separate code-smell systems it ships and why they are kept apart, checked against the source file by file rather than against a paraphrase of it.

The video’s claims, and why they needed checking

The video’s frame was specific enough to check directly: grill-me interrogates the user about a plan in five lines, and the Fowler code-smell vocabulary (Shotgun Surgery, Feature Envy, Data Clumps) lives in the plugin’s codebase-design skill, the one about designing deep modules. Both claims are plausible on their face. Five lines matches how short an aggressive system prompt can be, and codebase-design sounds like exactly the skill that would define what bad code looks like.

Neither survived reading the plugin’s own repository. The skills are split across five directories, not one: engineering, productivity, in-progress, misc, deprecated. grill-me does exist at seven lines, but it lives under productivity/, and its actual body is one instruction: call the Skill tool for grilling, a twenty-eight-line skill that does the interrogating. codebase-design is real too, and it does define a vocabulary, but it is a completely different one from Fowler’s.

The discipline behind the terse writing

The plugin ships a meta-skill called writing-for-agents whose whole subject is how to write the other twenty-four. It names three separate levers, and none of them is “shorter is better.”

The no-op test

A sentence earns its place only if it changes the model’s default behavior. The skill’s own wording: does it change what the model does, or does it just restate what the model would already do? A sentence that fails is deleted outright rather than trimmed, because a shortened restatement of a default is still a restatement.

Leading words

Terms are not decoration either. The skill calls a compact, pretrained concept a “leading word”: a token the model already carries a distributed definition for from its own training, reused instead of a paragraph of explanation. grilling’s own body spends almost nothing on mechanism because it is built entirely from three of these. “Design tree,” “frontier,” and “rounds” each stand in for a sentence of explanation, and once a reader knows the term, every later use of it costs one word instead of ten.

Information hierarchy

Length is not the enemy either, and this is the part a five-line-grill-me story misses. The skill defines a hierarchy: an in-file step is what the agent does in order, in-file reference is consulted on demand, and disclosed reference is pushed into a sibling file behind a pointer, loaded only when that pointer fires.

codebase-design runs 114 lines with a full glossary and ASCII diagrams, and none of it is padding by this test, because every line is reference material a reader genuinely needs on demand rather than a restated default. A 15-line skill and a 114-line skill can both be correctly pruned; the hierarchy, not the line count, is what the discipline actually measures.

Two code-smell vocabularies, kept deliberately apart

code-review’s smell list is a twelve-item version of the ones in Fowler’s Refactoring: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest. Each is phrased the same way, what it is and how to fix it, and both are bound by two rules stated once above the list: a documented repo standard overrides the baseline, and every smell is a labelled judgement call, never a hard violation.

codebase-design never uses that vocabulary at all. Its glossary defines Module, Interface, Implementation, Depth, Seam (credited to Michael Feathers), Adapter, Leverage, and Locality, each with an explicit warning against the word most people would reach for instead: avoid “unit” or “service” for Module, avoid “API” or “signature” for Interface, avoid “boundary” for Seam. A deep module pairs a small interface with a lot of implementation; a shallow one is the reverse, and the skill says to avoid it. It also names its own source and then partly rejects it: Ousterhout’s original metric measures depth as the ratio of implementation lines to interface lines, and the skill calls that framing out by name, because it rewards padding the implementation, using “depth as leverage” instead.

Neither vocabulary borrows from the other anywhere in the plugin. improve-codebase-architecture, which runs a codebase health scan, is told explicitly to use codebase-design’s words and not drift into “component,” “service,” “API,” or “boundary.” The two systems solve different problems: one names what is already wrong with a diff, the other names how to shape an interface before anything is wrong with it. Collapsing them into one list, the way a short summary would, loses the reason each exists.

Applying the discipline instead of describing it

Reading the discipline is one thing; using it is another, and the repo already had a place to use it. Its own release pipeline runs a code review before every merge, checked against a repo-specific checklist that had never had a generic code-smell dimension. The agent’s proposal was to fold code-review’s twelve-item baseline into that existing checklist as an eighth dimension, crediting the source, rather than running the plugin’s code-review skill as a second, separate pass. Two review outputs for one diff would have meant reconciling disagreements between them on every release; one checklist with a new dimension does not.

The same visit produced a domain glossary the repo did not have. I asked to seed it immediately rather than defer it, with terms pulled from real code (Article, Locale, Figure, Thumbnail, and eight more) rather than invented ones, each checked against the file that actually defines it before being written down.

The pruning test got used on the repo’s own writing too, on a narrower scope than a full rewrite. I chose to run only the no-op and leading-word tests against the repo’s two longest skill files, keeping every incident narrative and guard-rail table exactly as it was: writing-for-agents itself says that kind of material is a legitimate cache, “the unwritten convention, the reason behind a choice, the gotcha no config confesses,” not padding to prune.

What changed, verified

The pruning pass on the repo’s own skills confirmed the discipline more than it found bloat. Applying the no-op and leading-word tests to a 988-line release skill and a 609-line style guide found three legitimate cuts in each, not dozens. That is a low number by design, not a miss: most of both files’ length is incident memory, exact commands and exact failure modes learned from real releases, which writing-for-agents’s own rule protects rather than flags.

The new review dimension got its first real test on a diff that touched actual code, not just documentation, and it found something. While consolidating a duplicated fence-parsing routine into one shared function, the closing rule quietly weakened: it matched a fence marker’s leading text instead of requiring the whole line to be nothing but fence characters, the stricter rule the sibling function already used, and the new function’s own comment claimed to share that rule when it did not. Dimension 8, the one just added, caught it before the pull request merged. The bug was real, latent rather than live in the corpus at the time, and fixed the same session it was introduced. The smell baseline was not decoration on a checklist: it changed what got reviewed.

Summary

Matt Pocock’s mattpocock-skills plugin is terse because a meta-skill inside it defines exactly what to cut and what to keep: restated defaults go, dense pretrained terms replace explanations, and reference material moves behind a pointer rather than getting inlined. It ships two separate code-smell vocabularies, not one: Fowler’s, for a diff that has already gone wrong, and a modified Ousterhout’s, for shaping an interface before anything has. The video collapsed both distinctions, the vocabulary and the line count, and reading the source instead of the summary was what caught it. Using the discipline for real, folding one vocabulary into an existing review instead of running a second tool, made the difference visible: the checklist it changed caught a bug in itself before that release shipped.