Skip to content
Get packs

Improve Codebase Architecture

Finds shallow modules and refactor opportunities in a codebase, shows them in an HTML report, then helps pick one.

Source Download skill
Repository
mattpocock/skills
Stars
309,658
Licence
MIT
Files
3 files

What it does

When you ask an AI agent to review a project's structure, this skill makes it scan the code (weighting recently changed areas via git history), look for places where modules are hard to understand or test, and write a visual HTML report of refactoring candidates, each with a before/after diagram and a strength rating. After you pick one, the agent walks through the design decisions with you and can record terminology and rejected ideas in the project's glossary and decision records.

Great for

  • Developers who want a structured review of where a codebase is hard to test or navigate
  • Teams planning refactors who want candidates ranked with reasoning before committing to changes
  • Projects that already keep a GLOSSARY.md or docs/adr decision records

Skip it if

  • Small or single-file projects, where there is little architecture to review and the report adds noise
  • Anyone wanting automatic code changes: the skill is designed to propose and discuss, not implement, and it asks before proceeding
  • Projects with no git history, since the hot-spot step depends on git log

Try asking

  • “Review the architecture of this repo and suggest deepening opportunities as an HTML report”
  • “Look at the payments module for shallow modules and hard-to-test seams”
  • “Scan this codebase for refactors that would improve testability”
Step-by-step guide: how to use Improve Codebase ArchitectureInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 3 original files, the MIT licence and an attribution note.

    improve-codebase-architecture.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip improve-codebase-architecture.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip improve-codebase-architecture.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Name a specific module or pain point up front to skip the broad history scan and get focused results
  • Keep a GLOSSARY.md and ADRs in the project so the suggestions use your domain language and respect past decisions
  • Review the generated HTML file before acting on it: it is written to the OS temp directory and opened automatically, and the report loads external CDN scripts

What's inside

  • agents/openai.yaml
  • HTML-REPORT.md
  • SKILL.md

Redistributed unmodified from mattpocock/skills under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.