Preface¶

After using AI to write code, repositories often grow more complex faster than before. Features work, tests pass, but module interfaces keep expanding, concepts scattered across multiple small files, and truly hard-to-test areas remain uncovered—these issues don’t break out suddenly in a single git commit, but slowly slow down subsequent changes.

There are two common approaches. One is a full-scale refactoring based on experience, which carries high risk and is hard to review; the other is to directly ask an Agent to “fix the architecture,” which will easily rewrite a pile of files according to its own preferences, but cannot clearly explain whether the changes are worthwhile or conflict with existing decisions. The improve-codebase-architecture maintained by Matt Pocock takes a third path: first conduct an architecture survey, write the “modules worth deepening” into a visual report, let you select candidates, then move on to grilling, without modifying business code at any point.

It is included in the skills/engineering/improve-codebase-architecture/ directory of the mattpocock/skills repository, and is used together with codebase-design, grilling, and domain-modeling in the same repository. The author’s official description page is at aihero.dev.

What It Is¶

One-sentence positioning: Scan the codebase for deepening opportunities—refactoring candidates to turn shallow modules into deep modules—into a standalone HTML report, then conduct design grilling on the one you select. The goal is testability and making it easier for AI to navigate the repository.

The frontmatter of the official SKILL.md is as follows:
- name: improve-codebase-architecture
- description: Scan the codebase for deepening opportunities, present them as a visual HTML report, then grill the one you pick
- disable-model-invocation: true (The Agent will not call it automatically; you must enter /improve-codebase-architecture in the chat)

The repository README categorizes it as a User-invoked skill: it can only be activated proactively by you to orchestrate the workflow, rather than letting the model intervene automatically when writing features. The author emphasizes that it is a survey, not a rescue: run it regularly to prioritize follow-up work; for years-old ball-of-mud repositories, it can identify real candidates, but will not untangle the mess for you.

The design vocabulary comes from the same repository’s /codebase-design, with the core being deep modules as described by John Ousterhout in A Philosophy of Software Design: a large amount of behavior hidden behind a small, stable interface. The supporting skills also specify that they do not use “lines of implementation / lines of interface” as a depth metric (that kind of algorithm would encourage writing long implementations), and instead use depth-as-leverage—how much behavior the caller gets in exchange for learning a little bit of the interface.

Core Features and Highlights¶

Based on the official SKILL.md, the HTML-REPORT.md in the same directory, and the author’s site documentation, its capabilities can be divided into the following sections.

1. Define scope first, then explore organically¶

The first step of the workflow is Explore, and it explicitly calls out YAGNI: the benefit of deepening a module depends on whether it will be modified in the future. Therefore, the scan should prioritize code that has been actively changed recently:
- You specify a direction (a certain module, subsystem, or pain point)—follow your instructions and do not infer further on your own.
- Otherwise, first read a segment of git log --oneline to find recurring hot paths; if changes are too scattered with no hotspots, expand the scope.

Next, read the project’s domain glossary CONTEXT.md and the ADRs (docs/adr/) for the relevant area. The domain glossary names “good seams”; the ADRs record decisions that should not be revisited repeatedly. These two types of files are not runtime prerequisites: use domain nouns to name candidates if they exist (for example, “Deepen the Order intake module”), and the tool will run even if they do not.

The exploration itself does not follow rigid heuristics. The official requirements require you to note the “friction you feel when walking through the code,” with key points including:
- To understand a concept, you need to jump back and forth between many small modules.
- A module is shallow: its interface is almost as complex as its implementation.
- Pure functions are extracted only for easier testing, while real bugs are hidden in how they are called (no locality).
- Tightly coupled modules leak through seams.
- The current interface is untestable or very difficult to test.

For suspected shallow modules, perform a deletion test: delete it, and see whether the complexity is concentrated behind a smaller interface, or merely moved to the caller? Only candidates that “concentrate complexity” are worthy of being made into cards.

2. Output a one-off HTML report not checked into the repository¶

The candidates are not delivered as a long Markdown list, but as a single-file, self-contained HTML file placed in the operating system’s temporary directory to avoid polluting the repository. The temporary directory uses $TMPDIR, falling back to /tmp if unavailable (or %TEMP% on Windows), with a file name in the form architecture-review-*.html, with a new file generated each run. After writing the file, it will open it according to the platform (Linux xdg-open, macOS open, Windows start), and tell you the absolute path.

The report uses CDNs to load Tailwind and Mermaid: relationship diagrams (call graphs, dependencies, timelines) use Mermaid; more “editor-focused” graphics like quality charts, profiles, and folding animations use handwritten HTML/CSS/SVG. HTML-REPORT.md stipulates that each candidate must have a before/after comparison, with diagrams as the main body and short text.

Each candidate card includes:
- Files: Which files/modules are involved
- Problem: Why the current architecture causes friction
- Solution: What will be changed (in plain language, no specific interface design has been done at this point)
- Benefits / Wins: Explain using locality and leverage, and how testing will become easier
- Before / After: Side-by-side schematic diagrams
- Recommendation strength: Badges of Strong / Worth exploring / Speculative

There is a Top recommendation at the end of the report: which one to prioritize and why. If a candidate conflicts with an existing ADR, list it only if the friction is large enough to justify reopening the ADR, and add a warning; it is forbidden to list all theoretical refutations already vetoed by the ADR again.

There are hard constraints on wording. On the architecture side, you must use the vocabulary from /codebase-design: module, interface, depth, seam, adapter, leverage, locality; do not substitute terms like component, service, API, boundary. On the domain side, use the names from CONTEXT.md.

After generating the report, pause first and ask: “Which of these would you like to explore?” Before you select one, no interface proposals will be made and no code will be changed.

3. Grill only after selection, decisions are not diffs¶

Only after you select a candidate will /grilling be called, asking questions along the decision tree: constraints, dependencies, the shape of the deepened module, what to put behind the seam, and which tests can still pass. The output of this step is decisions, not patches. The main follow-up workflow outlined on the author’s site is: Decision → /to-spec → /to-tickets → /implement.

During the grilling process, /domain-modeling will be called to write the domain model into the repository:
- If the name of the deepened module is a concept not in CONTEXT.md → add it to CONTEXT.md (create the file if it does not exist).
- Clarify vague terms during the conversation → update CONTEXT.md on the spot.
- If you veto a candidate with the reason “it will be useful later” → you can ask whether to write it into an ADR to avoid bringing it up again in future reviews; temporary reasons like “not worth doing now” do not need to be recorded.
- To see multiple interfaces for the deepened module → run /codebase-design again, using its design-it-twice feature: parallel sub-Agents will present several very different interfaces (minimalist, flexible, optimized for callers, ports & adapters, etc.), then compare them based on depth, locality, and seam position.

Note: There is an entry in the skills.sh summary about “generating GitHub Issue RFCs”. The current SKILL.md in the repository does not include this step; formalizing the plan into work orders is the job of the subsequent /to-spec and /to-tickets skills, do not expect this Skill to open issues directly.

Installation and Activation¶

This Skill follows the universal SKILL.md format, and can be installed in tools that support Agent Skills such as Cursor, Claude Code, and Codex CLI. Matt Pocock’s repository provides two installation philosophies—do not install both, otherwise each Skill will appear twice.

Method 1: Claude Code official plugin (full set, read-only, updated with the author)¶

claude plugins install mattpocock-skills

You can also run this in a Claude Code session:

/plugin install mattpocock-skills

The plugin is available in the Claude Code official marketplace, no need to add a source first. This will install the entire set of engineering skills, not just this one.

Method 2: skills CLI (copy into editable files, for Cursor / Codex / other Agents)¶

Install only this single skill (the command given on the skills.sh page):

npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture

A shorthand is also available:

npx skills@latest add mattpocock/skills --skill improve-codebase-architecture

You can choose the target Agent during installation. For Cursor, the project-level directory is usually:

.cursor/skills/improve-codebase-architecture/SKILL.md

Or the cross-tool directory:

.agents/skills/improve-codebase-architecture/SKILL.md

According to Cursor’s documentation, it will also scan .agents/skills/ and .cursor/skills/ at the project level; the user-level directories correspond to ~/.agents/skills/ and ~/.cursor/skills/. For compatibility with other tools, Cursor will also read .claude/skills/ and .codex/skills/. Claude Code’s project-level directory is .claude/skills/, and the user-level directory is ~/.claude/skills/.

When installing the full set, the official README requires checking the setup-matt-pocock-skills option, then running /setup-matt-pocock-skills in each repository (selecting the issue tracker, triage labels, and documentation storage location). You can run the scan even if you only install this skill; but the complete workflow also depends on codebase-design, grilling, and domain-modeling from the same repository, so it is recommended to install them together.

After activation, enter /improve-codebase-architecture in the Agent chat. Since disable-model-invocation: true is in the frontmatter, the model will not automatically apply this skill when you describe “help me refactor the architecture”—you must explicitly use the slash command.

Typical Usage Examples¶

Daily Maintenance (no scope specified)¶

Invoke it in the repository root directory. The Skill will first check recent commit hotspots, then explore and generate a report:

/improve-codebase-architecture

The author recommends running it every few days, outside the main feature development cycle, to prioritize follow-up work rather than modifying code on the spot.

Before a major change (the most effective prompt according to the official)¶

When you already have a spec about to start work, focus the review on “how to make this change easy”:

/improve-codebase-architecture
What we are about to do next is: <paste the spec or requirements here>
Please only look at the modules that this change will touch, and ask: how can we make this change easy?
Pause after generating the HTML report, do not start grilling directly.

Official Explore rule: If you specify a scope, do not do a full repository walkthrough.

Only generate the report, no grilling first¶

The most common complaint in the author’s FAQ is that weaker models will skip the report and ask dozens or hundreds of questions based on their first thought. The Skill is designed to “first show the report, then grill only after you select”, but there is currently no separate no-grill mode. You can specify this when invoking:

/improve-codebase-architecture
don't grill me, just show the report.

After viewing the report¶

Open architecture-review-*.html in the temporary directory (you will need access to Tailwind / Mermaid CDNs, otherwise it may be unstyled raw HTML).
Select only one candidate for the current session. The author explains: Mixing reports, grilling, domain document edits, and code changes in the same window will clutter the context; the report file only exists in the temporary directory, what you really need to bring over is the single selected candidate itself.
After reaching a decision through grilling, use /to-spec to formalize it into a spec, and turn the remaining candidates into separate tickets to be picked up later. Do not jump directly from the report to implementation.

A self-check for a successful run (from the author’s site “It’s working if”):
- Candidates use domain concepts, not made-up class names.
- Candidates focus on recently modified files, not dead parts of the repository.
- No business code was modified during the run, the only new file is the HTML in the temporary directory.
- The report pauses and asks you which one to select.
- Each card explains benefits using locality / leverage, and describes how testing will become easier.
- When vetoing a candidate with a valid reason, it will propose writing it into an ADR.

Applicable Scenarios and Notes¶

Suitable For¶

Repositories that are already under iteration, and you want to regularly prevent structural decay (what the author calls routine upkeep).
Before starting a major feature, first ask “how to make this change easy”.
Repositories with inconsistent structures or left over from extensive vibe coding, where you want to first clarify the shape (brownfield audit).
Preparing to add tests, but the code is currently untestable: first find the missing seam, then write tests against the interface.

Do Not Use It As¶

An automatic refactoring tool. It explicitly does not modify code; refactoring happens in a separate session via the normal spec / ticket / implement workflow.
A replacement for /codebase-design. The latter is a vocabulary and design discipline (model-invoked), responsible for “how to deepen a selected module”; this Skill is a survey, responsible for “what should be put on the design table”. Using /codebase-design as a “go do it” command is a known failure mode: it has no own workflow, and the Agent will invent one and spin for a long time.
A roadmap for massive work. Use /wayfinder for planning across multiple sessions.
Diagnosis of specific bugs. That is the job of /diagnosing-bugs; only return to this Skill if you discover that “you can’t pin down a bug because there are no good seams”.

Known Limitations (per the author’s FAQ and SKILL.md)¶

It will almost never tell you “the repository is fine”. The skill is written to produce findings; the defense mechanism is the badges—if all are marked Speculative, it is equivalent to saying “no truly worthwhile work was found”.
HTML relies on CDNs. When offline or if security policies require SRI, Tailwind / Mermaid may fail to load, and the report will become unstyled, graphics-free raw HTML. The Agent itself cannot see the rendered result. The workaround is to instead require inline CSS and handwritten SVG. This is an unresolved rough edge.
The exploration step uses Claude Code’s Agent tool (subagent_type=Explore). Harnesses without this tool (such as some Codex environments) can still run, but parallel exploration may be skipped, resulting in less thorough scanning. A rewrite unrelated to the harness has been proposed, but has not yet been merged officially.
No accompanying TypeScript implementation guide. It will tell you where deepening should happen and what should go behind the seam; how to map this to package/directory structure is currently up to you.
Limited ability for out-of-control legacy repositories. The author acknowledges that it works very well on large repositories with acceptable structure; user feedback for “eight-year-old legacy, completely out of control” projects is that it helps a little but is not sufficient. If the repository does not even have a shared glossary, first use /grill-with-docs to establish CONTEXT.md and ADRs before running this Skill, and the output will be much better.

Summary¶

improve-codebase-architecture packages “how AI conducts architecture reviews” into a repeatable workflow: explore by hotspots → filter shallow modules with deletion tests → generate a visual report in a temporary directory → select one candidate to grill → formalize decisions into specs / tickets, rather than modifying code on the spot. It governs the prioritization and naming of technical debt, rather than completing refactoring for you.

Like other engineering skills in the same repository, it assumes you are willing to maintain a domain glossary and accept “align first, then act”. Running it every few days, or asking “how can we make this change easy” against a spec before a major change, is far more controllable than letting an Agent freely run a “optimize architecture” session.

Official address:
https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture

Improve Codebase Architecture: Let AI Conduct Architecture Review First Before Deciding Where to Modify