Agent Coder
Matt Pocock's Skills for Real Engineers: how to de-slop a codebase damaged by AI and keep it clean.
1. Executive summary
Matt Pocock's public repository Skills for Real Engineers is a set of small, composable agent skills taken from his own daily .agents directory. It is not a heavy process framework that takes ownership of how you work. Frameworks such as GSD, BMAD, and Spec-Kit try to help by owning the process, and in doing so they take away control and make bugs in the process hard to resolve. Pocock's bet is the opposite: keep the human in charge as the strategic programmer, and give the agent a tight set of engineering practices so it can be a strong tactical coder without burying the codebase in slop.
The intention of the repo is to restore software engineering fundamentals in an age where AI has made code cheap to produce and expensive to change. The companion talk for the cleanup method is Matt's YouTube video How To De-Slop A Codebase Ruined By AI (with one skill) (youtube.com/watch?v=3MP8D-mdheA). That video is the practical demonstration of the single skill that matters most for rescue work: /improve-codebase-architecture. This briefing summarises the intention, the vocabulary, the rescue loop, and the habits that stop a cleaned codebase from rotting again.
The headline claim in that video is worth taking seriously. LinkedIn-style posts that code is cheap and teams can now move faster than ever miss the second-order effect: AI has accelerated software entropy. Every change that does not take the whole system into account introduces little inconsistencies. Those inconsistencies snowball until the codebase is a ball of mud that is very hard to reverse if you do not know how. Pocock's skills exist to give you that method, without handing the steering wheel to an autonomous pipeline.
This ai-coder folder is a local working copy. The skills tree is a git submodule pointing at github.com/mattpocock/skills. Use it as a readable source of truth, then install the skills into each real product repo you want to clean or protect.
2. What the skills repo is for
Pocock built the skills to fix four failure modes he sees with Claude Code, Codex, and other coding agents. Each failure has a named practice rather than a vague prompt.
Failure mode | What goes wrong | The practice |
|---|---|---|
The agent did not do what you wanted | Misalignment. You thought the agent understood the change. The result proves it did not. | /grill-me and /grill-with-docs. The agent interviews you until the design tree is resolved. |
The agent is far too verbose | No shared language. The agent reinvents jargon every session and spends tokens explaining itself. | CONTEXT.md plus ADRs, built during grilling. One precise domain term replaces a paragraph. |
The code does not work | No feedback loop. The agent flies blind because types, tests, and runtime evidence are missing. | /tdd (red-green-refactor) and /diagnosing-bugs (reproduce, minimise, hypothesise, instrument, fix). |
You built a ball of mud | AI speeds up entropy. Shallow modules, leaked seams, and low locality make every later change harder. | /improve-codebase-architecture, plus /codebase-design vocabulary, run as periodic maintenance. |
Two installation philosophies exist. Do not use both in the same project or every skill appears twice. The Claude Code plugin is a managed, read-only bundle that updates when Pocock ships. The skills.sh installer (npx skills@latest add mattpocock/skills) copies editable skill files into your project so you can hack them. For this working copy we cloned the source repo itself, which is the tinkerer's path.
3. The video: de-slop with one skill
Primary reference: How To De-Slop A Codebase Ruined By AI (with one skill) — Matt Pocock.
The video is explicitly a cure, not only prevention. An earlier Pocock talk covers how to stop a codebase getting to this point, by designing deep modules from the start. This one is for the codebase that already feels beyond repair. The method is old software fundamentals, applied through one agent skill.
Pocock's framing of roles is the part most teams skip, and it is the reason the skill works. Agents are very good tactical programmers. They can get on the ground and make changes quickly. They need someone above them who is the strategic programmer. The skill lets the sergeant run around the codebase looking for deepening opportunities. You, the general, choose what is good for long-term health. This is not an AFK skill you fire and forget. It demands judgement from the human sitting above the model.
On a fast-moving codebase he recommends running the skill every couple of days. On a legacy codebase, the same skill is a good place to start before you let AI loose, because legacy usually means hard to change, and hard to change usually means lots of shallow modules. Before you start making changes you need a harness: tests around deep modules that have leverage and locality, so later agent edits do not silently break behaviour.
4. Shared vocabulary (use these words exactly)
The skill turns on one idea: depth, from John Ousterhout's A Philosophy of Software Design. The repo's /codebase-design skill insists you use these terms and not drift into component, service, API, or boundary. Shared language is the whole point. The YouTube video walks the same glossary before applying it to Pocock's course-video-manager codebase.
Term | Meaning | Why it matters when cleaning slop |
|---|---|---|
Module | Anything with an interface and an implementation. Scale-agnostic: a function, a package, or a slice. | Stops you refactoring 'components' while the real mess is a missing module. |
Interface | Everything a caller must know to use the module correctly: types, invariants, errors, ordering, config. | A wide interface is usually a shallow module wearing a disguise. |
Implementation | What sits inside the module. Distinct from an adapter, which is a concrete stand-in at a seam. | Depth hides implementation. Shallow modules leak it. |
Depth | Behaviour a caller can exercise per unit of interface they must learn. Deep = small interface, lots of behaviour. | The report hunts for shallowness and proposes deepenings. |
Seam | The location at which a module's interface lives. Where you can change behaviour without editing that place. | This is where tests and fakes go. Two parallel implementations of the same idea is a broken seam. |
Adapter | A concrete thing that satisfies an interface at a seam, for example a real clock and a fake clock. | One adapter is a hypothetical seam. Two adapters means the seam is real and worth keeping. |
Leverage | What callers get from depth: more capability per unit of interface they learn. | Deep modules make both humans and agents cheaper to operate. |
Locality | What maintainers get from depth: changes, bugs, and fixes concentrate in one place. | Slop spreads the same rule across files. Deepening puts it back in one module. |
Two tests from the design skill are worth memorising. The deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across many callers, it was earning its keep. Second: the interface is the test surface. Callers and tests should cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
5. How to clean up a codebase already ruined by AI
Do not start by asking an agent to 'optimise the code' or 'clean this up'. That produces local edits: extracted functions, extra types, renamed variables. Useful, and still surface-level. Cross-module coupling is invisible to that prompt. Use the architecture skill as a survey, then implement later through the normal build flow.
5.1 Prepare the repo once
Install the skills into the target product repo with npx skills@latest add mattpocock/skills. Include setup-matt-pocock-skills in the selection. Or, for Claude Code only, install the mattpocock-skills plugin. Do not do both.
Run /setup-matt-pocock-skills once per repo. Point it at your issue tracker (GitHub, Linear, or local files), your triage labels, and where docs should land.
If CONTEXT.md does not exist, create it. Write down what the important domain words actually mean in this project. Without that glossary the architecture report will talk in filename-speak instead of domain-speak.
Turn off auto-mode for this flow. The skill is a human-in-the-loop grilling session. Auto-mode fights that.
5.2 Run the survey
Invoke /improve-codebase-architecture. The skill first decides where to look. Deepening pays off on code that will change again, so it weights recent git hot spots unless you name a subsystem. It reads CONTEXT.md and existing ADRs, then explores for friction:
Understanding one concept requires bouncing between many small modules.
Modules are shallow: the interface is nearly as complex as the implementation.
Pure functions were extracted only for testability, while the real bugs live in how they are called (no locality).
Tightly coupled modules leak across their seams.
Parts of the codebase are untested, or hard to test through the current interface.
It then writes a self-contained HTML report to the OS temp directory, not into the repo. Each candidate card lists files, problem, solution, benefits in terms of locality and leverage, a before/after diagram, and a recommendation strength (Strong, Worth exploring, or Speculative). You pick one. The skill does not start refactoring yet.
5.3 Grill one candidate, then ticket it
Once you pick a candidate, the skill enters a grilling loop. You talk through constraints, the shape of the deepened module, what sits behind the seam, and which tests survive. In the video, Pocock demonstrates this on course-video-manager: the report found two parallel implementations of the same insertion-point / clip-section ordering rule, so frontend and backend could drift. Collapsing that into one module recovers locality. That is the kind of finding local 'cleanup' prompts never produce.
When the shape is agreed, do not dump a giant unattended refactor into the same session. Turn the decision into a spec or tickets (/to-spec, /to-tickets) and implement later with /implement and /tdd. Pocock's point in the video is that the survey is not the rescue. On a genuinely old codebase the skill will find real candidates, but it will not untangle the mud for you. You still choose, and you still ship through a harness of tests.
5.4 What good looks like after a deepening
One small interface. Callers learn less, and get more behaviour.
One place where the rule lives. A bug is fixed once.
A real seam, with tests that cross that seam, and adapters only where something actually varies.
Domain names from CONTEXT.md, not leftover AI filenames.
An ADR if you rejected a candidate for a load-bearing reason, so the next survey does not suggest it again.
6. How to keep a codebase clean
Cleanup without a maintenance cadence is a one-off tidy. Entropy starts again the next time an agent lands a feature without looking at the rest of the system. The rest of Pocock's engineering skills are the keep-clean operating system.
Habit | When | Why it prevents slop |
|---|---|---|
Grill before you build | Every non-trivial change | Misalignment is the most common failure. /grill-with-docs also sharpens CONTEXT.md and ADRs while you decide. |
Write the spec from the conversation | After grilling, before coding | /to-spec synthesises what you already agreed. /to-tickets cuts it into tracer-bullet work with blocking edges. |
Implement behind tests | Every feature and fix | /tdd forces red-green-refactor at agreed seams. Feedback is the speed limit. |
Review on two axes | Before commit | /code-review checks Standards (repo rules plus a Fowler smell baseline) and Spec (did we build the thing we ticketed) as parallel sub-agents. |
Survey architecture on a cadence | Every few days on a fast repo | /improve-codebase-architecture is periodic maintenance. It queues work. It does not auto-rewrite the system. |
Keep the domain model alive | Whenever a term is fuzzy | /domain-modeling and /grill-with-docs update CONTEXT.md inline. Shared language reduces token waste and naming drift. |
Route instead of inventing process | When you are unsure which skill to use | /ask-matt is a router over the user-invoked skills. Use it rather than inventing a new mega-prompt. |
A keep-clean rule that is easy to violate: do not let the agent invent seams for testability alone. One adapter means a hypothetical seam. Two adapters means a real one. Extracting pure functions so a unit test can call them, while the production bugs live in the callers, is how AI codebases get a false sense of coverage and no locality.
7. Suggested operating loop for this machine
Use this clone as the briefing and the upstream source. Apply the skills inside each product repository, not by copying this whole ai-coder tree into production apps.
Read this document and, if needed, watch the de-slop video once with the glossary in section 4 open.
In the target repo, install the skills and run /setup-matt-pocock-skills.
Write or refresh CONTEXT.md. If the project already has AGENTS.md or CLAUDE.md, keep domain language in CONTEXT.md and point the agent at it.
Run /improve-codebase-architecture. Pick one Strong candidate. Grill it. Ticket it. Implement with /tdd.
Repeat on a cadence. On a hot codebase, every few days. On a quieter one, after each burst of agent-authored work.
For new work, grill first. Do not start a feature as an unattended implementation session.
8. What this folder contains
Path | Role |
|---|---|
skills/ | Git submodule of github.com/mattpocock/skills. Readable source, including /improve-codebase-architecture and /codebase-design. |
_docs/agent-coder.docx | This executive briefing. |
README.md | Short pointer for GitHub visitors. |
To refresh the submodule later: git submodule update --remote skills. Review the diff before you rely on new skill behaviour. Pocock ships changes; you choose when to take them.
9. Sources
Matt Pocock, Skills for Real Engineers: https://github.com/mattpocock/skills
Matt Pocock, How To De-Slop A Codebase Ruined By AI (with one skill): https://www.youtube.com/watch?v=3MP8D-mdheA
Installer and catalogue: https://skills.sh/mattpocock/skills
John Ousterhout, A Philosophy of Software Design (deep modules). Kent Beck, Extreme Programming Explained (invest in design every day). Michael Feathers, Working Effectively with Legacy Code (seams). Eric Evans, Domain-Driven Design (ubiquitous language).
End of briefing. The skill finds candidates. You decide. Tests hold the line.