Improve Codebase Architecture

Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

57 stars 5 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add javimosch/supercli --skill improve-codebase-architecture
Manual install
git clone --depth 1 https://github.com/javimosch/supercli.git /tmp/supercli
mkdir -p ~/.claude/skills
cp -r /tmp/supercli/.agents/skills/improve-codebase-architecture ~/.claude/skills/improve-codebase-architecture

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the 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.

## Glossary

Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md).

- **Module** — anything with an interface and an implementation (function, class, package, slice).
- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
- **Implementation** — the code inside.
- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
- **Adapter** — a concrete thing satisfying an interface at a seam.
- **Leverage** — what callers get from depth.
- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.

Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):

- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- **The interface is the test surface.**
Read the full skill on GitHub

Details

Skill name
improve-codebase-architecture
Path
.agents/skills/improve-codebase-architecture/SKILL.md
License
MIT
Repo updated
2 November 2026

FAQ

What does the Improve Codebase Architecture skill do?

Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

How do I install the Improve Codebase Architecture skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add javimosch/supercli --skill improve-codebase-architecture. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Improve Codebase Architecture popular?

It lives in javimosch/supercli, which has 57 GitHub stars and 5 forks, and is included in 1 curated skill list.

Related skills

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.