codebase-design · Skill Details

Mechanism

When It Triggers · How It Works · What It Produces

Breaks down how the skill works and what it produces, so you can quickly judge whether it fits your scenario and value.

Trigger: Invoked when the user wants to design or improve a module's interface, find deepening opportunities, decide seam placement, or make code more testable. Other skills (e.g., /improve-codebase-architecture, /tdd) also reference it automatically for deep-module vocabulary.
Mechanism: Defines a precise vocabulary where each term specifies what to say and what to avoid — "Module" means anything with an interface and implementation (avoid component/service/API); "Interface" includes type signatures, invariants, ordering constraints, and everything a caller must know (not limited to TypeScript's interface keyword). Provides deep vs shallow module visual comparisons, design principles, and testability guidelines.
Output: A consistent, reusable design language and set of principles that agents and human engineers share when discussing module design, reducing communication ambiguity and improving design decision quality.

Use Cases

Two Typical Use Cases

Scenario 01

Redesigning a module's interface

When refactoring an overly complex module, a developer invokes `/codebase-design` for deep-module design vocabulary and principles. The skill provides precise definitions of Module, Interface, Depth, and principles like the deletion test and "the interface is the test surface." The developer uses this language to analyze whether the current module is shallow and how to hide more behaviour behind a small interface.

Scenario 02

Designing a testable interface for a new feature module

Before starting new feature development, an engineer wants to ensure testability. Invoking `/codebase-design` provides three testability guidelines: "accept dependencies, don't create them," "return results, don't produce side effects," and "small surface area." With included TypeScript examples, the engineer can design inherently testable interfaces, reducing mock and test scaffolding work later.

Skill Relationships

Which Skills I Use · Which Skills Use Me

Dependency relationships read as "the upper tier points to the lower tier." The current Skill sits in the middle tier — above are Skills that depend on it, below are Skills it depends on.

Tier 1 · These Skills Use Me

Tier 2 · Current Skill

codebase-designStyle Guide

Tier 3 · I Use These Skills

No explicit dependency on other Skills

Full Relationship Graph

Browse this skill's relationships within its skillset. Click a node to switch the side panel; use the search box to jump to any skill.

Skill File

SKILL.md

Open in GitHub ↗

SKILL.mdLoading from GitHub…

Skill Composition

Open in GitHub ↗

SKILL.md25.0%
other75.0%

▸skills/codebase-design/
▸codebase-design
- ·DEEPENING.md
- ·DESIGN-IT-TWICE.md
- ·SKILL.md
- ▸agents
  - ·openai.yaml

Per the Agent Skills spec, SKILL.md is the only required file. The colored bars classify the rest into the three spec-aligned optional directories (scripts / references / assets) and an 'other' bucket. The full directory tree is below.

Related in Skillset

You May Also Need These Skills

ask-matt

A router skill for the entire skillset: when the user can't remember which skill to use or which flow fits their situation, they invoke this to get a recommendation. It describes the main "idea → ship" flow (grill-with-docs → to-spec/to-tickets → implement), plus on-ramps (triage, diagnosing-bugs, wayfinder), codebase health (improve-codebase-architecture), vocabulary layers (domain-modeling, codebase-design), and standalone skills (grill-me, prototype, research, teach). Following its map leads users to the correct workflow entry point.

Workflow

code-review

A two-axis code review skill: reviews a diff (from a fixed point to HEAD) along both Standards (coding standards + Fowler smell baseline) and Spec (faithful implementation of the originating issue/PRD). Both axes run as parallel sub-agents to avoid context pollution. The report aggregates findings without merging conclusions, ensuring "passes standards but implements the wrong thing" and "implements the right thing but breaks conventions" are both surfaced independently.

Workflow

diagnosing-bugs

A disciplined diagnosis loop for hard bugs and performance regressions. The core idea is to first build a tight feedback loop — no hypothesis phase without one. Six phases: build feedback loop → reproduce + minimise → generate 3-5 falsifiable hypotheses → instrument by prediction → fix + regression test → cleanup + post-mortem. If the codebase architecture can't lock down the bug, it recommends handing off to the improve-codebase-architecture skill.

Workflow

domain-modeling

An active discipline for building and sharpening a project's domain model: challenges terms in real time during conversation, clarifies fuzzy language, stress-tests scenarios, cross-validates code against the model, updates CONTEXT.md inline, and sparingly creates ADRs (only when the decision is hard to reverse, surprising without context, and the result of a real trade-off). Not a static glossary — a living process that continuously polishes the domain model.

Workflow