Development & Code COMMUNITY New

Improve Codebase Architecture

You get your codebase scanned for shallow modules, receive the refactoring candidates as a visual HTML report and work through the one you choose with Claude, step by step.

Level ●● Intermediate
Saves manually hunting for worthwhile refactoring spots in your code
Updated 2026-11-16
Available in: claude-codecoworkclaude-desktop

What is Improve Codebase Architecture?

Improve Codebase Architecture is a skill for Claude Code that scans a codebase for places where shallow modules can be turned into deep ones. The goal is code that is easier to test and a structure that AI agents can navigate more easily. The proposals are written as a self-contained HTML file in your system's temp directory, so nothing new ends up in the repository.

First, the skill narrows down where to look. If you name a module, a subsystem or a specific pain point, it starts there. Otherwise it reads the commit history and focuses on areas that change often. A sub-agent with a fresh context then walks the code and checks suspicious modules with a deletion test. Each candidate gets a card in the report with files, problem, solution, benefits, a before and after diagram and a recommendation level.

Then you pick a candidate, and the skill works through the open decisions with you: constraints, dependencies, the shape of the new module and which tests remain. Along the way it maintains the domain glossary in GLOSSARY.md and offers to record well-founded rejections as an ADR. The skill suits teams with grown codebases and expects the skills codebase-design, grilling and domain-modeling to be available.

Who it is for

For developers and tech leads who want to restructure existing codebases while keeping domain terms and architecture decisions consistent.

Use cases

  • You take over a grown codebase and want to know where a refactoring would improve testability the most.
  • A subsystem is hard to follow because you keep jumping between many small modules, and you are looking for a cleaner cut.
  • Your team wants to document architecture decisions so that rejected refactoring ideas do not come back in later reviews.

What Improve Codebase Architecture does

Focused scope

Without a direction from you, the skill reads the commit history and concentrates on areas that change often. If you name a module or problem, it starts right there.

Deletion test for shallow modules

The skill checks suspicious modules by asking whether removing them would concentrate complexity or merely move it. Only modules where it concentrates become candidates.

Visual HTML report

The report uses Tailwind and Mermaid via CDN plus custom SVG graphics. Each proposal shows files, problem, solution, benefits and a side by side before and after diagram.

Recommendation levels and top pick

Each candidate gets a badge: Strong, Worth exploring or Speculative. The report closes with the refactoring you should tackle first and the reasoning behind it.

Decision round for your pick

Once you choose, the skill uses the grilling skill to work through the decisions with you, such as dependencies, interface shape and which tests still hold.

Glossary and ADRs respected

The skill uses the terms from GLOSSARY.md, adds new terms there and respects existing ADRs. If a proposal conflicts with an ADR, it flags this visibly in the report.

Say this to activate the skill

"Run Improve Codebase Architecture on this repository.""Use Improve Codebase Architecture to check the order module for shallow modules.""Show me an HTML report of where a refactoring pays off in this project.""Let's go through the first candidate from the architecture report."

Install

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

The command installs the original version from the author's repository (Vercel skills CLI, needs Node.js), add -g for all projects. We do not host a copy: updates come straight from the author. Need help with setup? How to install skills →

Figures with source and date

GitHub stars
≈ 325,100
Installs
1,271,467
On skills.sh since
13 Mar 2026
Last change in the repository
12 Nov 2026
Licence
MIT

As of 16 Nov 2026. Sources: GitHub, skills.sh. The figures change daily; we show the state of our last lookup.

Checked automatically

Revision of the repository, checked on 16 Nov 2026.

  • Automated check on 2026-11-16 (revision 5863806): 3 files in the skill folder read by pattern search. It found no hidden characters, no instructions to override rules, no download-and-run and no access to credentials.

Independent checks on skills.sh, as of 16 Nov 2026

Gen Agent Trust Hub Pass
Socket Pass
Snyk Warn

Full results on skills.sh ↗

Good to know

  • The skill does not start automatically. You have to invoke it explicitly.
  • It calls the skills codebase-design, grilling and domain-modeling. The install command names only this one skill, so check that the others are available.
  • The HTML report loads Tailwind and Mermaid via CDN. To display it fully, your browser needs access to these sources.
  • During the decision round, the skill writes directly to GLOSSARY.md in your project.
  • One auditor on skills.sh reports a warning (Snyk). Read its notes before bringing the skill into projects with sensitive data.
  • The check is an automated pattern search, not a security guarantee, and reads the skill folder only. The command always installs the author's current version; later versions have not been reviewed by us.

Frequently asked questions about Improve Codebase Architecture

What is Improve Codebase Architecture?

Improve Codebase Architecture is a skill for Claude Code that scans a codebase for shallow modules and outputs refactoring proposals as an HTML report. It then walks you through the proposal you choose in detail.

How do I install Improve Codebase Architecture?

You install Improve Codebase Architecture with the command 'npx skills add mattpocock/skills --skill improve-codebase-architecture'. After that, the skill only runs when you invoke it explicitly.

Is Improve Codebase Architecture free?

Improve Codebase Architecture is released under the MIT license, so you can use it freely. To run it, you need an AI agent that supports skills, such as Claude Code.

Who is Improve Codebase Architecture for?

Improve Codebase Architecture is for teams that want to make a grown codebase easier to test and easier for AI agents to read. It is especially useful when the project keeps a domain glossary and ADRs, which the skill draws on.

What data does Improve Codebase Architecture send?

Improve Codebase Architecture writes its report locally to your system's temp directory. When opened, the HTML file loads Tailwind and Mermaid from external CDNs. The code itself is read by the AI agent you use.

Which files does Improve Codebase Architecture change?

Improve Codebase Architecture stores its report outside the repository. Inside the project, it adds to or updates GLOSSARY.md during the decision round and creates the file if it is missing. It only writes ADRs after asking you.

Share this skill

About this skill

Improve Codebase Architecture comes from mattpocock and is an open-source project maintained by its author and community.

Author: mattpocock / github.com. Source: github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture. Licence: MIT.

Curated by Collective Brain, an AI and automation digital agency from Hamburg, together with WhiteFox Automations. More vetted skills in the skills catalog.

Working in Germany, Austria or Switzerland? We help teams roll out Claude, in English or German.

Want this skill tailored to your team?

Improve Codebase Architecture is a strong starting point. A skill gets really powerful once it knows your workflows, templates and tone of voice. We build custom skills for teams, from analysis to rollout, and connect them to our work in AI consulting.

Request a custom skill →