Skills DirectoryCurated open-source Skills from GitHub
English

improve-codebase-architecturecommit 7739eaeSKILL.md · Architecture Tuning

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.

npx skills add mattpocock/skills --skill improve-codebase-architecture
Permissions
  • read-repo
  • write-files
  • shell
  • network
Compatible with
Claude Code, Codex, Copilot, Gemini CLI
GitHub
308.7k
Source
Community · Matt Pocock
Status
Scan passed
License
MIT
Category
Architecture Tuning
Repository
github.com/mattpocock/skills/skills/engineering/improve-codebase-architecture

Core rule

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

Execution Phases

  1. Phase 01Scope 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. Phase 02Explore for friction

    A sub-agent walks the code looking for shallow modules, missing locality and leaky seams, applying the deletion test.

  3. Phase 03Write 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. Phase 04Grill 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)

CapabilityNeededDetails
File writesLimitedOnly the HTML report in the temp directory, GLOSSARY.md and ADRs under docs/adr/; it does not edit code.
Command executionLimitedRuns git log to read commit history and open, xdg-open or start to open the report.
Network outboundNot requiredThe skill makes no network calls; the generated report loads Tailwind and Mermaid from CDNs when opened in a browser.

SKILL.md frontmatter (YAML)

SKILL.md frontmatter (YAML)commit 7739eae
---
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
---

Related skills

A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.
Markdown version GitHub