Category: Development
Improve Codebase Architecture
Finds architectural friction in a codebase and proposes refactors toward deep, testable modules.
Works with
What it does
- Surfaces shallow modules, tight coupling, and untested seams
- Applies John Ousterhout's deep module principle (small interface, large implementation)
- Generates radically different interface designs with parallel subagents and recommends the best
- Writes a GitHub issue RFC with the problem, trade-offs, and rationale
When to use it
A good starting point when every change touches too many files, or when agents struggle to navigate your codebase.
How to install
- Run the command below in your terminal. Pick the agents you use (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more) and it installs into the right folder.
npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture
- To install manually, download the
improve-codebase-architectureskill folder from the GitHub repository and copy it into your agent's skills folder, such as~/.claude/skills/or.cursor/skills/. - Ask your agent for a related task and the skill is used automatically.