Skip to content
Skills Library
Programming · Review & audit

improve-codebase-architecture

/improve-codebase-architecture

Survey a codebase for deepening opportunities, present source-backed candidates as a static HTML report, then explore whichever one the user picks. Use when the user asks to improve a codebase's architecture or to find refactors that make it more testable and easier for agents to navigate.

Repository
skills ↗
Licence
MIT
Last repository change
10.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
23
Scripts
1
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/render-report.py

What it does and when to use it

Survey a codebase for deepening opportunities, present source-backed candidates as a static HTML report, then explore whichever one the user picks. Use when the user asks to improve a codebase's architecture or to find refactors that make it more testable and easier for agents to navigate.

Original author description

Survey a codebase for deepening opportunities, present source-backed candidates as a static HTML report, then explore whichever one the user picks. Use when the user asks to improve a codebase's architecture or to find refactors that make it more testable and easier for agents to navigate.

How it works

  1. Process
  2. Provenance
Original SKILL.md headings · 74 lines, 964 words
SKILL.md preview
---
name: improve-codebase-architecture
description: Survey a codebase for deepening opportunities, present source-backed candidates as a static HTML report, then explore whichever one the user picks. Use when the user asks to improve a codebase's architecture or to find refactors that make it more testable and easier for agents to navigate.
license: MIT
metadata:
  verified: "2026-11"
  requires: "codebase-design"
  source: "https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/improve-codebase-architecture/SKILL.md"
  source-files: "skills/engineering/improve-codebase-architecture/SKILL.md"
  source-revision: 49dd158d1076134a641b33efb035946536778336
  local-changes: "Kept hotspot-first scoping, the friction questions, deletion test, candidate cards and the pick-then-explore loop; the report is now rendered by a script that escapes all content and is static and offline by default, with optional pinned Mermaid in strict mode and a stated network dependency; repository terms are kept; no product edits before the user picks; no mandatory sub-agent, local server or auto-open."
---

# Improve codebase architecture

Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and navigability for agents and people. The deliverable is a bounded, read-only report; no product code changes until the user picks a candidate and authorizes the work.

This skill is informed by the project's domain model and built on a shared design vocabulary:

- Read the `codebase-design` skill (required) for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", adapter counts as a heuristic). Use these terms in your reasoning; in the report, keep the repository's own names for its parts and map them to these terms where it helps.
- The project's domain glossary and decision records (at its configured paths, often `GLOSSARY.md` and `docs/adr/`) name good seams and record decisions this survey should not re-litigate.

## Process

### 1. Explore

**Scope before you scan.** Deepening a module pays off by making future changes to it easier, so weight the parts of the codebase that change often. Decide *where* to look before you look:

- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
- Otherwise, walk back a good stretch of the commit history (`git log --oneline --name-only`) to find the hot spots, the files and areas that keep coming up, and let those pull your attention first. If changes are scattered with no clear hot spot, widen the net.

Read the domain glossary and any decision records in the area first. Then walk the code and note where you experience friction:

- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow**, with an interface nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, while the real bugs hide in how they're called (no **locality**)?
- Where do tightly coupled modules leak across their seams?
- Which parts are untested, or hard to test through their current interface?

Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? "Concentrates" is the signal you want. A separate exploration agent is optional, for a large codebase, and is charged to any shared run budget.

**Done when** each candidate has evidence a reader can check: file paths with line ranges, the commits or change counts behind the hot spot, and the friction observed. Claims stay as narrow as that evidence; a survey of one subsystem says nothing about the rest.

### 2. Present candidates as an HTML report

Write the candidates as JSON in the shape [references/report-format.md](references/report-format.md) describes, then render and check them:

```sh
python3 <skill-dir>/scripts/render-report.py candidates.json --check
python3 <skill-dir>/scripts/render-report.py candidates.json --output "<tmpdir>/architecture-review-<timestamp>.html"
```

Python 3.12 or later is required; no packages are needed. Find `python3.12` or a newer versioned interpreter on PATH; if `python3` is older, use that interpreter or `uv run --python 3.12` before the script path. Exit 0 rendered, 1 findings in the JSON (`--check` lists them as JSON), 2 usage or unreadable input. Resolve `<tmpdir>` from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), so nothing lands in the repo and each run gets a fresh file. The renderer escapes every value and produces a static page with no scripts or network requests. Add `--mermaid-cdn` only when the user accepts that diagrams load a pinned Mermaid build from a CDN; the page then says so. Tell the user the absolute path; open it only if they ask and the host can.

Each candidate card shows:

- **Files**: which files and modules are involved, with line ranges
- **Problem**: why the current architecture causes friction
- **Solution**: plain-English description of what would change
- **Wins**: in terms of locality and leverage, and how tests would improve
- **Before / after diagram**: the shallowness and the deepening, side by side
- **Evidence**: the commits, counts and lines behind the claim
- **Recommendation strength**: `Strong`, `Worth exploring` or `Speculative`

End with a **top recommendation**: which candidate you'd tackle first and why.

**Decision-record conflicts**: if a candidate contradicts an existing decision record, surface it only when the friction is real enough to warrant revisiting that decision, and mark it in the card (for example, "contradicts ADR-0007, but worth reopening because…"). Don't list every theoretical refactor a decision forbids.

Do not propose interfaces yet. After the report is written, ask the user: "Which of these would you like to explore?"

### 3. Explore the chosen candidate

Once the user picks a candidate, walk the decision with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, which tests survive. The `grilling` skill structures that interview; the `architect` skill produces interface alternatives and the design artifact.

Keep the domain model current as decisions crystallize, within the authority to edit docs (the `domain-modeling` skill):

- **Naming a deepened module after a concept not in the glossary?** Add the term, creating the glossary lazily if it doesn't exist.
- **Sharpening a fuzzy term during the conversation?** Update the glossary right there.
- **User rejects the candidate with a load-bearing reason?** Offer a decision record, framed as: "Want me to record this so future architecture reviews don't re-suggest it?" Offer only when a future explorer would need the reason; skip ephemeral and self-evident ones.

Done when the user has the report, every candidate's evidence is checkable, and any chosen candidate has moved into design with its decisions recorded where the project keeps them.

## Provenance

Adapted from Matt Pocock's improve-codebase-architecture skill and its HTML-REPORT reference. See [references/SOURCES.md](references/SOURCES.md) and `LICENSE-mattpocock`. The repository test `tests/improve-codebase-architecture/run.sh` renders hostile content and checks escaping, offline output and the Mermaid settings.
Files in this package (23)
  • LICENSE-mattpocock 2 KB
  • SKILL.md 7 KB
  • agents/openai.yaml 1 KB
  • evals/examples.md 2 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-activation-1-core6.md 4 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-activation-1-core6fix.md 5 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-activation-2-core6.md 4 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-activation-2-core6fix.md 5 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-near-miss-1-core6.md 4 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-near-miss-1-core6fix.md 4 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-near-miss-2-core6.md 4 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-near-miss-2-core6fix.md 4 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-near-miss-3-core6.md 4 KB
  • evals/results/2026-11-08-codex-gpt-6.1-sol-near-miss-3-core6fix.md 5 KB
  • evals/results/2026-11-09-claude-claude-opus-5-5-activation-1-claude.md 5 KB
  • evals/results/2026-11-09-claude-claude-opus-5-5-activation-2-claude.md 5 KB
  • evals/results/2026-11-09-claude-claude-opus-5-5-near-miss-1-claude.md 4 KB
  • evals/results/2026-11-09-claude-claude-opus-5-5-near-miss-2-claude.md 4 KB
  • evals/results/2026-11-09-claude-claude-opus-5-5-near-miss-2-temp-stop-retry-claude.md 5 KB
  • evals/results/2026-11-09-claude-claude-opus-5-5-near-miss-3-claude.md 5 KB
  • references/SOURCES.md 3 KB
  • references/report-format.md 5 KB
  • scripts/render-report.py 12 KB

Versions

RepositoryScoreLicence
This page · cravingmaker/skills100MIT
TerminalSkills/skills100Apache-2.0
callmeteus/gti-skills100MIT
akillness/jeo-skills100MIT
sammcj/agentic-coding100Apache-2.0
drvoss/everything-copilot-cli100MIT
hachemsoft/ia-toolkit100MIT
niekcandaele/claude-helpers100MIT
runwield/runwield100MIT

Database snapshot: 13.11.2026 · package version dbfb5d1bfafb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100jidoka-improve-architecture
    Scan a codebase for deepening opportunities, report them as Markdown in the chat, grill through the one the user picks and file it as a spec. Use when the user asks to find refactoring or deepening opportunities, or about large or hard-to-change modules.
  • 100codebase-improve-architecture
    Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
  • 100codebase-design
    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.
  • 100codebase-design
    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.
  • 100codebase-design
    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.
  • 100codebase-design
    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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.