improve-codebase-architecture
Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
Best for Codebase refactoringWorks with GitHubLow risk
⌘source
- author
@mattpocock- language
- Shell
★36kstars
2.9kforks
Apr 29, 2026
✦overview.md
Key Features
- ·Surface architectural friction
- ·Propose deepening opportunities
- ·Increase testability
- ·Improve AI-navigability
- ·Use consistent glossary terms
Use Cases
- →Improve codebase architecture
- →Find refactoring opportunities
- →Consolidate tightly-coupled modules
- →Make codebase more testable
Best for
- ✓Codebase refactoring
- ✓Architecture improvement
Not ideal for
- !Greenfield projects
- !Quick feature additions
FAQs
name
improve-codebase-architecture
description
Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
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.
Glossary
Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.
- Module — anything with an interface and an implementation (function, class, package, slice).
- Interface — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
- Implementation — the code inside.
- Depth — leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.
- Seam — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
- Adapter — a concrete thing satisfying an interface at a seam.
- Leverage — what callers get from depth.
$install
1-click copynpx skills add mattpocock/skills --skill improve-codebase-architectureSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
4/ 5
very goodClear and well structured, with only minor parts that might need a second read.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
3/ 5
mediumPartially actionable with several concrete steps, but still missing important details.