Guide · Agent skill
How to use the Improve Codebase Architecture agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The improve-codebase-architecture skill lets an AI agent review a project's structure and find places where modules are hard to test or navigate. It writes those findings as a visual HTML report of refactoring candidates, then talks you through whichever one you choose. This guide explains what the skill does, how to install it, how to trigger it, and what it needs from your machine and project.
Improve Codebase Architecturemattpocock/skills · MIT Download the skill Quick start
- 1Download the skill ZIP. Get the improve-codebase-architecture ZIP from this page. Keep it somewhere you can reach from your terminal or file manager.
- 2Unzip into a skills folder. Unzip the skill into ~/.claude/skills/ for personal use, or into .claude/skills/ inside your project for a single repository.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
- 4Ask for a review. Make a plain request such as asking the agent to review the project's architecture for places that are hard to test or navigate.
- 5Open the HTML report. Let the agent open the report with xdg-open, open, or start, and note the absolute path it gives you. The browser needs internet access to load Tailwind and Mermaid.
- 6Pick a candidate and discuss it. Choose one of the candidates. The agent will walk through the design decisions with you and offer to update GLOSSARY.md or record an ADR.
What is an agent skill and what does this one do?
An agent skill is a folder of instructions and supporting files that an AI agent can load when a task matches it. This skill is for reviewing architecture. Its goal is to find refactors that turn shallow modules into deep ones, with the aim of making code easier to test and easier for an AI to navigate.
The skill works in stages. It first scopes the review, using git history to find the areas of the codebase that change most often, since changes there pay off most. It then explores the code, looking for friction such as concepts that require jumping between many small modules, or modules whose interface is nearly as complex as their implementation. For suspected shallow modules it applies a deletion test: would deleting the module concentrate complexity, or just move it?
- Scans the code, weighting recently changed areas through git history
- Writes a self-contained HTML report with one card per candidate
- Gives each candidate a before/after diagram and a recommendation strength of Strong, Worth exploring, or Speculative
- Ends with a Top recommendation section
- Asks which candidate you want to explore, and does not propose interfaces or change code until you pick one
How do you install the Improve Codebase Architecture skill?
Download the ZIP for the skill from this page. Unzip it so the skill folder sits in one of two places: your personal skills folder at ~/.claude/skills/, or a project-specific .claude/skills/ folder inside the repository you want to review. A personal install makes the skill available across projects. A project install keeps it scoped to one codebase.
If you use the Claude apps rather than a local setup, you can upload the skill instead. Open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/improve-codebase-architecture/
- Project install: .claude/skills/improve-codebase-architecture/ inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/How do you trigger the skill with a natural request?
Ask the agent directly to review your project's architecture. The skill's frontmatter sets disable-model-invocation to true, so it is not meant to start on its own. Name the task in plain words and, if you have a specific area in mind, name it. The skill uses your direction when you give one and skips its own inference about hot spots.
Requests that work well describe the goal: where the code is hard to test, where the structure is hard to follow, or which subsystem you are planning to refactor.
- Review this project's architecture and suggest where it's hard to test.
- Look at the payments module for shallow modules and refactoring candidates.
- Find places in this codebase that are hard to navigate, and show me a report.
- Where should we deepen modules before we plan the next refactor?
What happens during a review?
The agent first checks git history with git log to find hot spots. If the changes are scattered with no clear hot spot, it widens the search. It reads GLOSSARY.md and any ADRs in docs/adr/ for the area it is touching, then spawns a sub-agent with a fresh context window to walk the code.
The report is written to your OS temp directory, not your repository, so nothing new lands in the repo. The file name includes a timestamp so each run creates a new file. The agent opens the report for you and tells you the absolute path. It then asks which candidate you would like to explore. The skill is built to propose and discuss, not to implement.
- Report location: the OS temp directory, using $TMPDIR, falling back to /tmp (or %TEMP% on Windows)
- Opening the file: xdg-open on Linux, open on macOS, start on Windows
xdg-open <path>How do you read the HTML report?
Each candidate has a card listing the files involved, the problem, the proposed solution, and the benefits in terms of locality, leverage, and testing. The before/after diagram is custom-drawn to show the shallowness and the deepening. Some diagrams use Mermaid for graph-shaped relationships such as call graphs, dependencies, and sequences. Others are hand-built layouts.
If a candidate contradicts an existing ADR, the card shows a warning callout. The skill only raises these when the friction is strong enough to justify reopening the decision.
- Strong, Worth exploring, and Speculative badges show recommendation strength
- Warning callouts mark candidates that conflict with an ADR
- The report ends with a Top recommendation
How does the grilling step work after you pick a candidate?
Once you pick a candidate, the agent walks the design decisions with you. The conversation covers constraints, dependencies, the shape of the deepened module, what sits behind the seam, and which tests would survive the change.
As decisions settle, the agent can update your project's domain records. If the deepened module is named after a concept missing from GLOSSARY.md, the term is added, and the file is created if it does not exist. If you sharpen a fuzzy term, GLOSSARY.md is updated on the spot. If you reject a candidate for a lasting reason, the agent offers to record an ADR so future reviews do not re-suggest it. It skips ephemeral reasons such as not worth it right now.
- Adds new domain terms to GLOSSARY.md
- Offers an ADR only for load-bearing rejection reasons
- Calls other skills by name, including codebase-design, grilling, and domain-modeling
What are the safety notes?
This skill runs scripts and uses the network. The agent runs git log and shell commands to open the report. When you view the report, the browser loads Tailwind and Mermaid from CDNs, so you need internet access for the diagrams and styling to render. The report itself is generated locally in the temp directory.
The skill proposes and discusses changes but does not implement them, and it asks before proceeding. The source does not describe any automatic code edits, so review anything the agent suggests before you apply it yourself. The source also does not say whether the companion skills it calls are bundled in this download, so confirm they are installed before you rely on the full workflow.
- Runs scripts: yes, including git log and the command that opens the HTML file
- Uses network: yes, for Tailwind and Mermaid from CDNs when viewing the report
- Writes the report to the OS temp directory, not the repository
Tips for getting useful results
Give the skill a git history to work with. A project with no git history gives the hot-spot step nothing to rank by, so the skill is a poor fit there. Name a subsystem when you know where the pain is, since that narrows the scan and produces a more focused report.
Keeping a GLOSSARY.md and docs/adr/ folder in your project makes the review sharper. The skill uses the glossary to name seams and uses ADRs to avoid re-suggesting settled decisions.
- Use GLOSSARY.md and docs/adr/ records if your project has them
- Skip very small or single-file projects, where the report adds noise
- Expect proposals and discussion, not automatic code changes
What people use it for
- Finding which modules are shallow and hard to test before planning a refactor sprint
- Reviewing a subsystem you suspect is hard to navigate, and getting candidates ranked with reasoning
- Documenting rejected refactors as ADRs so future architecture reviews do not re-suggest them
- Building a shared domain vocabulary in GLOSSARY.md while discussing a deepened module
Frequently asked questions
Is the Improve Codebase Architecture skill free?
The skill is published under the MIT licence, as stated on this page. The source does not mention pricing for any other part of your setup, so check the terms of the agent platform you run it in.
What do I need to run the improve-codebase-architecture skill?
You need git, because the skill runs git log to find recently changed areas. You also need a way to run a shell command so the report can open, and internet access in your browser to load Tailwind and Mermaid from CDNs. A GLOSSARY.md and docs/adr/ folder are optional but useful.
Where do I install the skill?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps you can instead upload it under Settings, Capabilities, then Skills.
Will the skill change my code automatically?
No. The skill is designed to propose and discuss refactors, not implement them, and it asks before proceeding. You make any changes yourself or ask the agent separately.
Why does the skill need git history?
The hot-spot step runs git log to find the files and areas that keep changing. Because refactors pay off most in code you change often, the skill gives those areas extra weight. A project with no git history does not suit this skill.
Does the report go into my repository?
No. The HTML report is written to the OS temp directory, using $TMPDIR with a fallback to /tmp, or %TEMP% on Windows. Each run creates a new timestamped file, and the agent gives you the absolute path.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you want a structured, ranked review of where your codebase is hard to test or navigate, especially if you already keep a GLOSSARY.md or ADRs. Skip it for small or single-file projects, projects without git history, or if you want an agent to make code changes automatically, since it is built to propose and discuss instead.
Download the skill