Kipt

Improve codebase architecture skill: what it does and how to install it

Matt Pocock's improve codebase architecture skill scans your repo for shallow modules and writes an HTML report of refactor candidates. How to install it.

By the Kipt team · Updated 23 October 2026

Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 23 October 2026

What is the improve codebase architecture skill?

The improve codebase architecture skill has your coding agent survey a codebase for places where a refactor would make code easier to change and test, then lay out the candidates as a visual HTML report and talk through the one you choose. It is for developers whose agent-written code is getting harder to work in and who want a regular, structured look at where to invest.

It lives in mattpocock/skills, and the README recommends running it "once every few days". The skill's description: "Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick."

As of 23 October 2026, its skills.sh page listed about 1.2 million installs.

What does it do?

The core idea is depth; the README introduces it with a quote from John Ousterhout's A Philosophy of Software Design. A deep module hides a lot of behavior behind a small interface; a shallow one has an interface nearly as complex as its code. The skill hunts for shallow modules and proposes "deepening" them. It runs in three steps:

  1. Explore. If you name an area, it looks there. Otherwise it reads recent git log history to find hot spots, reads your GLOSSARY.md and any ADRs in docs/adr/, then spawns a sub-agent to walk the code and note friction: concepts spread across many small files, pure functions extracted only for tests, modules leaking across their seams. Each suspect gets the deletion test: would deleting it concentrate complexity, or just move it?
  2. Report. It writes a self-contained HTML file to your OS temp folder (architecture-review-<timestamp>.html), opens it, and prints the path. Each candidate is a card with the files, the problem, the solution, the benefits, a before and after diagram, and a strength badge: Strong, Worth exploring or Speculative. A "Top recommendation" section closes it. Then it asks which candidate you want to explore and stops.
  3. Grilling loop. For the candidate you pick, it loads the grilling skill and interviews you about constraints, what goes behind the seam and which tests survive. Along the way it loads domain-modeling to add or sharpen terms in GLOSSARY.md, and offers to record a rejected candidate as an ADR so later runs don't suggest it again.

It uses a fixed vocabulary from the repo's codebase-design skill (module, interface, depth, seam, adapter, leverage, locality) and tells the agent not to drift into words like "service" or "component".

What's in the folder:

  • SKILL.md: the process above, with disable-model-invocation: true.
  • HTML-REPORT.md: the report scaffold, diagram patterns (Mermaid graphs plus hand-built boxes and SVG) and styling rules.
  • agents/openai.yaml: Codex metadata ("Improve Codebase Architecture") with allow_implicit_invocation: false.

How do you install the improve codebase architecture skill?

The README offers a self-updating plugin or editable files, and says to pick one per agent so you don't get every skill twice.

Claude Code plugin (whole set). From the README, using Anthropic's official plugin marketplace:

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

Claude Code namespaces plugin skills, so look for /mattpocock-skills:improve-codebase-architecture.

Codex plugin. From the README:

codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock

Just this skill, as editable files. The SKILL.md calls three other skills by name, so install them together with the skills CLI:

npx skills add mattpocock/skills --skill improve-codebase-architecture --skill codebase-design --skill grilling --skill domain-modeling

Add -g for every project. For Claude Code the folders land in .claude/skills/ in your project, or ~/.claude/skills/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills. The skill needs to read your repo and its git history, so it suits Claude Code or Codex rather than a claude.ai chat.

Prerequisites. The skill's docs page lists none. If GLOSSARY.md or ADRs exist, it uses your domain's own nouns. The README separately suggests running /setup-matt-pocock-skills once per repo before using the engineering skills; it asks about your issue tracker, triage labels and where docs should go.

How do you use it?

Type /improve-codebase-architecture, ideally with a direction. The docs say the most effective prompt is pointing it at an upcoming spec and asking "how can we make this change easy?"

Example prompts (suggestions, not quotes from the repo):

  • /improve-codebase-architecture We're adding team billing next month. How can we make that change easy?
  • /improve-codebase-architecture Focus on the checkout flow; it breaks every time we touch it.
  • /improve-codebase-architecture Don't grill me, just show the report.
  • /improve-codebase-architecture Find the missing seams in the import module before we write tests for it.

Requirements: a git repo, a browser to view the report, and network access when you open it, since the report loads Tailwind and Mermaid from CDNs. No API keys.

The docs suggest one candidate per session. Pick one, grill it, take the decision into the repo's to-spec skill, and turn the rest into tickets for later.

Tips and limits

From the repo's docs, not from testing:

  • It may grill too soon. The most common complaint is the agent skipping the report and interviewing you about its first idea. Weaker models do this more. Say "don't grill me, just show the report" when you invoke it.
  • It rarely says "all good". The skill exists to find candidates. If every card is Speculative, treat that as nothing found.
  • Legacy code is hard. It works well on unstructured repos but may go in circles on very old ones. The docs suggest running grill-with-docs first to build a shared vocabulary.
  • Codex and other harnesses. The docs say the scan can be less thorough in harnesses without Claude Code's sub-agent tooling.
  • Security audits. As of 23 October 2026, skills.sh showed Socket as Pass, and Gen Agent Trust Hub and Snyk as Warn (both medium). Snyk (analysed 29 September 2026) flagged the CDN scripts the report loads at runtime. Gen Agent Trust Hub also noted that the report template sets Mermaid's securityLevel to loose, puts repo content such as git logs and ADRs into the HTML unescaped, and opens the file automatically with open, xdg-open or start. Read SKILL.md and HTML-REPORT.md before installing, and be careful running it on a repo you don't trust.
  • License. MIT, so you can edit the skill, for example to drop the CDN scripts.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files; for a repo with many skills, like this one, it shows a list to pick from, so you can take codebase-design, grilling and domain-modeling too. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Matt Pocock or mattpocock/skills.

Similar skills

Questions

What is the improve codebase architecture skill?

improve-codebase-architecture is an Agent Skill in Matt Pocock's mattpocock/skills repo. You run /improve-codebase-architecture, the agent surveys the codebase for shallow modules that could become deep ones, writes the candidates to an HTML report in your temp folder, then interviews you about the one you pick. It does not change code.

Does improve-codebase-architecture refactor my code?

No. The repo's docs call it a survey, not a refactoring tool. A run produces a conversation, one HTML file outside the repo and, during the interview, edits to GLOSSARY.md and optional ADRs. You do the refactor later in a separate session.

What do I need to install with it?

The skill calls three other skills from the same repo: codebase-design, grilling and domain-modeling. Installing the whole collection as a plugin covers that. With the skills CLI, add all four with --skill flags.

Can the agent run it on its own?

No. Its frontmatter sets disable-model-invocation: true, so in Claude Code it only runs when you type it, and its Codex metadata sets allow_implicit_invocation: false.

Why does the HTML report show up unstyled?

The report loads Tailwind and Mermaid from CDNs, so it needs network access when you open it. The repo's docs say offline or locked-down setups break it silently, and suggest asking for inline CSS and hand-built SVG diagrams instead.

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.