# Improve Codebase Architecture (improve-codebase-architecture)

> Finds refactors that turn shallow modules into deep ones, shows them in a visual HTML report, then grills through the one you pick.

- Category: [Architecture Tuning](https://www.myskills.tools/en/categories/architecture-tuning/)
- Source: Community · Matt Pocock
- Repository: https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture (commit 7739eae)
- SKILL.md: https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/SKILL.md
- Install command: `npx skills add mattpocock/skills --skill improve-codebase-architecture`
- License: MIT
- Compatible with: Claude Code, Codex, Copilot, Gemini CLI
- Permissions: read-repo ✓, write-files ✓, shell ✓, network ✗
- Status: Scan passed
- A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.

## Core rule

Scope before you scan: weight the parts of the codebase that have recently changed instead of refactoring everything.

## Execution Phases

1. **Scope the search** — Take the user's direction if given; otherwise use git log to find hot spots. Read GLOSSARY.md and relevant ADRs first.
2. **Explore for friction** — A sub-agent walks the code looking for shallow modules, missing locality and leaky seams, applying the deletion test.
3. **Write the HTML report** — Writes a self-contained HTML file to the OS temp dir, with before/after diagrams and a strength badge per candidate plus a top pick.
4. **Grill the chosen one** — Walks constraints, dependencies and the deepened module's shape with the user, updating GLOSSARY.md and offering an ADR when warranted.

## Permissions (summarised from SKILL.md)

| Capability | Needed | Details |
|---|---|---|
| File writes | Limited | Only the HTML report in the temp directory, GLOSSARY.md and ADRs under docs/adr/; it does not edit code. |
| Command execution | Limited | Runs git log to read commit history and open, xdg-open or start to open the report. |
| Network outbound | Not required | The skill makes no network calls; the generated report loads Tailwind and Mermaid from CDNs when opened in a browser. |

## SKILL.md frontmatter (YAML)

```yaml
---
name: improve-codebase-architecture
description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
disable-model-invocation: true
---
```

Home: https://www.myskills.tools/en/ · URL: https://www.myskills.tools/en/skills/improve-codebase-architecture/