Agent skill · software engineering · mattpocock
improve-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
Why this skill is useful
Adds a comprehensive HTML report generation script that visualizes architectural improvements and deepening opportunities in the codebase.
What it needs
Requires git, mermaid, tailwindcss installed locally. About 4k tokens when loaded. Last updated 2026-08-06. 207,363 stars on the source repository.
What this skill does
Improve Codebase Architecture Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability. This command is informed by the project's domain model and built on a shared design vocabulary: Call the Skill tool with "codebase-design" for the architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary." The domain language in CONTEXT.md gives names to good seams; ADRs in docs/adr/ record decisions this command should not re-litigate. Process 1. Explore Scope before you scan: YAGNI. Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide where to look before you look: If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below. Otherwise, walk back a good stretch of the commit history (git log --oneline) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net. Read the project's domain glossary (CONTEXT.md) and any ADRs in the area you're touching first. Then spawn a sub-agent to walk the codebase. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills mattpocock/improve-codebase-architecture