$ skilldirectory
— zsh — registry.skilldirectory.dev
skill library blog

home / Coding / Improve Codebase Architecture Skill by @mattpocock

Improve Codebase Architecture Skill by @mattpocock

FREE
github stars★ 3,15,437updatedOct 2026repo@mattpocock
$git clone https://github.com/mattpocock/skills

The skill is the skills/engineering/improve-codebase-architecture folder inside that repository. Copy it into the folder your agent loads skills from; check your agent's documentation for where that is.

Read the opening of the original SKILL.md
# Improve Codebase Architecture

Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

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

- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
- The domain language in `GLOSSARY.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.

## Process

### 1. Explore
…

Excerpt only, quoted from the author's repository. Open the repository for the complete file.