improve-architecture · rohitg00 — Claude Code skill: diagnose and refactor
improve-architecture audits code structure, identifies tangles in boundaries and dependencies, and proposes a ranked list of minimal moves that relieve the strain—no rewrite, only a plan you approve first.
MIT ★ 2,966 updated 2026-09-29
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflowWhat improve-architecture does
The skill maps an area of your codebase, finds load-bearing problems in its shape, and lists the smallest structural moves that improve it. It starts by charting the current layout: entry points, modules, data flow. Then it hunts for real strain—god modules everything depends on, leaky boundaries, duplicated logic that drifts, cyclic dependencies, seams in the wrong places—and ranks moves by leverage: pain relieved per unit of work. For significant changes, it suggests a decision record in docs/decisions/.
The output is a prioritized plan you review before any code moves. The skill diagnoses and recommends; it does not rewrite on its own. Each proposed move solves a named problem, not a taste preference.
What it helps with
- find modules that become bottlenecks because everything imports them
- spot duplicated logic that diverges across implementations
- break circular dependencies between components
- align module boundaries with the shape of your domain
- move seams so the codebase bends where it changes
Example prompts for the agent
- Audit the auth subsystem in
src/auth/and identify the three highest-leverage moves to improve its structure - Everything in our system pulls from
utils—how do we untangle and split it? - Review the data models and propose minimum shifts to draw a clean boundary between business logic and storage layers
How to install improve-architecture
1Plugin marketplace
/plugin marketplace add rohitg00/pro-workflow/plugin install pro-workflow@pro-workflowThis installs the whole pro-workflow plugin with all its skills
2Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill improve-architecture -a claude-code3Manually: put the files in place
~/.claude/skills/improve-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/improve-architecture/
1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill improve-architecture -a codex2Manually: put the files in place
.agents/skills/improve-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill improve-architecture -a cursor2Manually: put the files in place
.cursor/skills/improve-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rohitg00/pro-workflow skills/improve-architecture2Manually: put the files in place
.github/skills/improve-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill improve-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/rohitg00/pro-workflow --path skills/improve-architectureManually: put the files in place
.devin/skills/improve-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about improve-architecture
How do I install improve-architecture in Claude Code?
Run these in order: /plugin marketplace add rohitg00/pro-workflow, then /plugin install pro-workflow@pro-workflow, then npx skills add rohitg00/pro-workflow --skill improve-architecture -a claude-code. Configuration lands in ~/.claude/skills/improve-architecture/SKILL.md.
What does the improve-architecture skill do?
It maps your code structure, finds strain points like tangled boundaries and duplication, and gives you a ranked list of the smallest moves that relieve them. It diagnoses and proposes; it does not rewrite.
Do I need tests before using the skill?
Not always. The skill recommends; you decide which moves to make. For large structural changes, it often suggests landing behind green tests first, so refactors are safer.
Source text
SKILL.md · MIT
---
name: improve-architecture
description: Audit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite. Use when a codebase feels tangled, hard to change, or is becoming a ball of mud, or when asked to improve or refactor architecture.
user-invocable: true
---
# improve-architecture
Invest in the shape of the system a little at a time rather than paying for a
rewrite later. This skill diagnoses and proposes; it does not rewrite on its own.
## Method
1. **Map first.** Get the current shape before judging it - entry points,
modules, data flow, who calls whom. Reuse `module-map` for the one-screen
view; do not skip to opinions.
2. **Find the strain.** Look for the load-bearing problems, not style nits:
- God modules that everything imports and nothing can change safely.
- Leaky boundaries - a module reaching into another's internals instead of
its surface.
- Duplicated logic that drifts (the same rule implemented three ways).
- Wrong seams - the code is split where it does not bend and fused where it
does.
- Cyclic dependencies.
- A shape that fights the domain (see `domain-modeling` - boundaries in code
should track boundaries in the language).
3. **Propose the smallest move.** For each problem, the least change that
relieves it: extract a boundary, collapse a duplicate, invert a dependency,
move a seam. Prefer a sequence of safe steps over one big cut.
4. **Rank by leverage.** Order the moves by pain relieved over effort. Say which
are safe now and which need a test net first (pair with `tdd`).
5. **Record the big calls.** For a structural change a future reader would
question, write a decision record in `docs/decisions/NNNN-slug.md`: context,
choice, alternatives rejected, why.
## Guardrails
- Diagnose, do not rewrite. The deliverable is a plan the user approves before
any code moves.
- No churn for taste. A move must relieve a named strain; "cleaner" is not a
reason.
- Three similar lines beat a premature abstraction - do not trade duplication
for indirection unless the duplication actually drifts.
- Keep behavior fixed. Structural moves are refactors; land them behind green
tests.
## Output
A prioritized list: each item is the problem, the smallest move, the risk, and
whether it needs a test net first. Plus decision records for the big moves. No
code changes until the user picks what to do.
© Rohit Ghumare · MIT · rohitg00/pro-workflow
Similar skills
All skills for Code review and refactoring →improve-architecture by other authors comes first.