improve-codebase-architecture Skill for Claude: Scan for Refactors, Get an HTML Report

Scans your codebase for refactors that make modules deeper, shows them in an HTML report, then interviews you about the one you pick.

Installs: 1.2M; on skills.sh
Stars: 309.2K; on GitHub
Files: 2; besides SKILL.md
Updated: Nov 2026; last repo commit

improve-codebase-architecture looks for places where understanding one idea means jumping between many small modules. It starts with the files that changed most recently, spawns a helper agent to explore, and writes a self-contained HTML report to your temp folder with a card per candidate, a before and after diagram and a strength badge.

You start it with /improve-codebase-architecture; it never runs on its own. It proposes no interfaces until you choose one candidate. Then it runs the grilling skill with you. It also needs codebase-design and domain-modeling from the same repo.

Good for

Developers inheriting a codebase that is hard to navigate or test
Teams planning a refactor who want options ranked before anyone writes code
People who want AI-friendly, easier-to-test modules

Install improve-codebase-architecture

Claude Code

Copy this prompt.

Install the improve-codebase-architecture skill in Claude Code. Run this command:

claude plugin install mattpocock-skills@claude-plugins-official

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The plugin installs the whole set and updates itself. The skills CLI route must name codebase-design, grilling, domain-modeling too, because improve-codebase-architecture hands work to them. Claude Code names plugin skills /plugin-name:skill-name, so after the plugin install the full name is /mattpocock-skills:improve-codebase-architecture; the README lists /improve-codebase-architecture, which is not confirmed for plugin installs. The README also asks you to run /setup-matt-pocock-skills once per repo.

From the project README. Source.

What's in the skill

When it loads

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Sections in SKILL.md

Process
1. Explore
2. Present candidates as an HTML report
3. Grilling loop

Key facts

Author: Matt Pocock
License: MIT
Last commit: Nov 1, 2026
Files it bundles: SKILL.md, HTML-REPORT.md (report template) and a Codex agents/openai.yaml
Needs: codebase-design, grilling and domain-modeling skills from the same repo
Starts: Only when you type /improve-codebase-architecture
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn

What it includes

Reads git history for hot spots, then sends a helper agent through the code
It looks for shallow modules, leaky seams and hard-to-test parts, and applies a "deletion test" to suspects.
Runs code · 1. Explore
Writes architecture-review-<timestamp>.html to the temp folder and opens it
Cards show files, problem, solution, benefits, before and after diagrams and a Strong, Worth exploring or Speculative badge. Nothing lands in your repo.
Runs code · 2. HTML report
Ends the report with which candidate to do first and why
It marks any candidate that contradicts an existing ADR.
Top recommendation
Walks the decision tree for the candidate you pick
Calls the grilling skill on constraints, dependencies, the shape of the deepened module and which tests survive.
3. Grilling loop
Adds terms to GLOSSARY.md; offers an ADR if you reject a candidate for a lasting reason
Uses domain-modeling. Files are created only when needed.
Write · Glossary and ADR updates
Optionally explores alternative interfaces in parallel via codebase-design
Only if you ask to explore alternatives.
Design it twice

From the official docs

Permissions

Low risk

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

skills.sh audits
Gen Agent Trust Hub pass, Socket pass, Snyk warn. skills.sh
Nothing lands in the repo from the scan
The report goes to the temp folder so nothing is added to the working tree.

Technical details

Turning on read-only	The scan and report write only to the temp folder. Files in your repo change only during the grilling step, and only if you agree.
Talks to	Tailwind and Mermaid CDNs, when you open the report in a browser
Sign-in and keys	None. No account or API key.
Scopes	Runs git log and reads your files, through a helper agent Writes an HTML report to your OS temp folder and opens it May add terms to GLOSSARY.md or an ADR during the grilling step

Questions

What does improve-codebase-architecture do?

It scans a codebase for "deepening" refactors, turns shallow modules into deep ones, and presents them in an HTML report. After you pick one, it interviews you about the details.

How do I install it?

Use the install box above. It installs this skill with codebase-design, grilling and domain-modeling, which it calls.

Does it change my code?

Not in the scan. The report goes to your temp folder, not the repo, and it proposes no interfaces until you pick. During the grilling step it may add terms to GLOSSARY.md or offer an ADR.

Does it need an API key?

No. The HTML report loads Tailwind and Mermaid from CDNs, so viewing it needs internet.

Is it safe?

Gen Agent Trust Hub and Socket pass it; Snyk warns on skills.sh. It runs git log and opens the report with your system opener, and the helper agent reads your files within your normal permissions.

improve-codebase-architecture vs grill-with-docs?

grill-with-docs starts from a plan you have. This skill starts from the code, finds candidates, then grills you on the one you choose.

Information

updated Nov 2, 2026

Repository: mattpocock/skills
Folder: skills/engineering/improve-codebase-architecture

mattpocock/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

mattpocock/skills README · github.com
skills CLI commands · github.com
Claude Code skills · code.claude.com
improve-codebase-architecture SKILL.md · github.com
improve-codebase-architecture on skills.sh · skills.sh