improve-architecture
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.
- Installs
- 110
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/rohitg00/pro-workflow --skill improve-architecture- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads improve-architecture automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
- Map first. Get the current shape before judging it - entry points,
modules, data flow, who calls whom. Reuse
module-mapfor the one-screen view; do not skip to opinions. - 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).
- 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.
- 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). - 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.
FAQ
What does the improve-architecture skill do?
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.
How do I install improve-architecture?
Run npx skills add https://github.com/rohitg00/pro-workflow --skill improve-architecture in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/improve-architecture/ (personal) or .claude/skills/improve-architecture/ (project).
Which AI agents can use improve-architecture?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is improve-architecture safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains improve-architecture?
It is published by rohitg00 in rohitg00/pro-workflow. It has 110 recorded installs.
More from rohitg00/pro-workflow
token-efficiency
rohitg00/pro-workflow
Reduce token waste by 40-60% through anti-sycophancy rules, tool-call budgets, one-pass coding, task profiles, and read-before-write enforcement. Inspired by drona23/claude-token-efficient.
pro-workflow
rohitg00/pro-workflow
Complete AI coding workflow system. Orchestration patterns, 18 hook events, 8 agents, cross-agent support, reference guides, and searchable learnings. Works with Claude Code, Cursor, and 32+ agents.
wrap-up
rohitg00/pro-workflow
End-of-session ritual that audits changes, runs quality checks, captures learnings, and produces a session summary. Use when saying "wrap up", "done for the day", "finish coding", or ending a coding session.
deslop
rohitg00/pro-workflow
Remove AI-generated code slop, unnecessary comments, and over-engineering from the current branch diff. Cleans up boilerplate, simplifies abstractions, strips defensive code, and in skill-file mode lints SKILL.md files for quality. Use when cleaning up code, simplifying, removing boilerplate, before committing, or when reviewing a skill before promoting it.
learn-rule
rohitg00/pro-workflow
Capture a correction or lesson as a persistent learning rule with category, mistake, and correction. Stores, categorises, and retrieves rules for future sessions. Use after mistakes or when the user says "remember this", "don't forget", "note this", or "learn from this".
session-handoff
rohitg00/pro-workflow
Generate a structured handoff document capturing current progress, open tasks, key decisions, and context needed to resume work. Use when ending a session, saying "continue later", "save progress", "session summary", or "pick up where I left off".
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.