improve-codebase-architecture

Identifies shallow modules and proposes deepening refactors rendered as an HTML architecture report.

3|Updated Jan 9, 2026
One-click install
npx skills add https://github.com/craft-ts/craft-ts --skill improve-codebase-architecture-craft-ts
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/craft-ts/craft-ts/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/craft-ts/craft-ts --skill improve-codebase-architecture-craft-ts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, scattering logic across tightly-coupled files and making testing and navigation difficult. This Skill surfaces that architectural friction and proposes concrete deepening refactors grounded in the project's own domain language and ADRs. ## Core Features & Use Cases - Architecture exploration: Uses an Explore sub-agent to find shallow modules, leaked seams, and untestable code, applying the deletion test to validate candidates. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory with Tailwind and Mermaid diagrams showing before/after visualizations, recommendation-strength badges, and a top recommendation. - Grilling loop and interface design: Walks the design tree with the user, updates CONTEXT.md with new domain terms, offers ADRs for rejected candidates, and spawns parallel sub-agents to design alternative interfaces. - Use Case: A team with a sprawling order-processing pipeline asks for an architecture review; the Skill produces a report showing how collapsing six shallow wrappers into one deep module concentrates tests at a single interface. ## Quick Start Ask the assistant to review this codebase's architecture and generate an HTML report of deepening opportunities.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find refactoring opportunities in a large codebase?▼

Run an architecture review that explores the codebase for shallow modules whose interfaces match their implementation complexity. The Skill applies a deletion test to each candidate and renders findings as an HTML report with before/after diagrams and recommendation-strength badges.

What is a deep module versus a shallow module?▼

A deep module hides a large amount of behavior behind a small interface, giving callers leverage and maintainers locality. A shallow module has an interface nearly as complex as its implementation, so deleting it just moves complexity rather than concentrating it.

Does the architecture review modify my repository files?▼

The HTML report is written to the OS temp directory, not the repo. However, during the follow-up design conversation the Skill may update CONTEXT.md with new domain terms or offer to record an ADR when a candidate is rejected for a load-bearing reason.

How does the review handle existing ADRs that conflict with a suggestion?▼

Candidates that contradict an existing ADR are only surfaced when the friction is real enough to warrant revisiting the decision. They are marked with a warning callout in the report rather than listed as routine suggestions.

When should I not introduce a seam or port between modules?▼

Avoid introducing a seam when only one adapter exists, since a single-adapter seam is just indirection. The Skill follows the rule that two adapters, typically production plus test, justify a real seam.