# Can an agent tell you where your architecture actually hurts?

Canonical URL: https://bestskillsforclaude.com/en/skills/improve-codebase-architecture
Language: en
Skill: improve-codebase-architecture
Publisher: Matt Pocock (https://github.com/mattpocock)
Source: https://github.com/mattpocock/skills
License as stated by the publisher: MIT
Runtime: Claude Code and agents that support the skills CLI
Category: Build and ship
Last reviewed: 2026-08-05

It can produce candidates. Choosing which ones matter is still your call.

## Short answer
The improve-codebase-architecture skill scans a codebase for opportunities to simplify and deepen modules, presents the findings as a report, and only then explores the candidates you select. The staged shape is the point: it is a diagnosis tool that refuses to start rewriting before you have chosen.

Best for: Codebases that grew fast and now leak details between modules.
Skip it if: The project is small enough that you already know exactly where the problems are.

## What to remember
- Report first, change later. That order is what makes it safe to run.
- Scope it to a subsystem, because a whole repository report is too big to act on.
- Findings are candidates, not verdicts. Some will be wrong for reasons only your team knows.
- It pairs with grill-me when you want the reasoning stress tested before you commit.

## What it changes in practice
Architecture work usually fails for social rather than technical reasons: nobody can agree on where to start, so nothing starts. A concrete list of candidates with reasons attached turns that argument into a decision.
Presenting findings as a report also keeps the agent from doing the most dangerous thing available, which is refactoring several modules at once while you watch.

## Where it disappoints
It sees the code, not the history. Some awkward boundaries exist because of a constraint that is not written down anywhere, and the skill will confidently propose removing them.
Large reports also invite scope creep. The discipline of picking one candidate is entirely on you.

## Install and first run
1. Install it with the skills CLI from mattpocock/skills, published under MIT.
2. Run it on one area rather than the whole repository, so the report stays reviewable.
3. Pick one or two candidates. A list of thirty findings is a way of choosing nothing.

## Questions
### Does it change code automatically?
It reports first and explores the candidates you select, rather than refactoring on sight.

### How large a codebase can it handle?
Scope it to a subsystem. Whole repository reports tend to be too large to act on.

### Who maintains it?
Matt Pocock, in his public skills repository under the MIT license.

## Sources
- mattpocock/skills on GitHub: https://github.com/mattpocock/skills
- Agent skills directory listing: https://skills.sh

## Other languages
- Spanish: https://bestskillsforclaude.com/es/skills/improve-codebase-architecture
- Brazilian Portuguese: https://bestskillsforclaude.com/pt-br/skills/improve-codebase-architecture
- Japanese: https://bestskillsforclaude.com/ja/skills/improve-codebase-architecture