Agent skill · software engineering · sickn33
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 detailed HTML reporting script for architectural improvements that includes visualizations and specific domain language not commonly known.
What it needs
Requires mermaid, tailwind installed locally. About 4k tokens when loaded. Last updated 2026-08-07. 44,571 stars on the source repository.
What this skill does
Improve Codebase Architecture When to Use Use when this workflow matches the user request: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. Source: mattpocock/skills (MIT). 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: Run the /codebase-design skill 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 — 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 Read the project's domain glossary (CONTEXT.md) and any ADRs in the area you're touching first. Then use the Agent tool with subagenttype=Explore to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: Where does understanding one concept require bouncing between many small modules? Where are modules shallow — interface nearly as complex as the implementation? Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)? Where do tightly-coupled modules leak across their seams? Which parts of the codebase are untested, or hard to test through their current interface? Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want. 2. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills sickn33/improve-codebase-architecture--bb9081