Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 24 October 2026
What is the codebase design skill?
The codebase design skill gives your coding agent a fixed vocabulary for designing modules, so you and the agent mean the same thing by "interface", "seam" and "deep". It is for developers who want agent-written code with small interfaces that hide real work, and for anyone using other skills from the same repo that depend on these words.
It comes from mattpocock/skills, which Matt Pocock describes in the README as "My agent skills that I use every day to do real engineering - not vibe coding." The skill's description reads: "Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary."
The README frames the problem as a "ball of mud": agents speed up coding, so they also speed up software entropy. As of 24 October 2026, the skill's skills.sh page listed about 849,900 installs (snapshot, 24 October 2026).
What does it do?
The repo's docs for codebase-design are blunt: "It is a reference, not a process. It runs no loop, produces no artifact, and never stops to ask you a question." The glossary is the skill.
The terms, as defined in the SKILL.md:
| Term | Meaning | Words to avoid |
|---|---|---|
| Module | Anything with an interface and an implementation, at any scale | unit, component, service |
| Interface | Everything a caller must know: types, invariants, ordering, error modes, config, performance | API, signature |
| Depth | Behaviour a caller or test can exercise per unit of interface they learn | |
| Seam | Where you can alter behaviour without editing in that place; where an interface lives | boundary |
| Adapter | A concrete thing that satisfies an interface at a seam | |
| Leverage | What callers get from depth | |
| Locality | What maintainers get from depth: change and bugs stay in one place |
Four principles follow:
- Depth is a property of the interface, not the implementation. A deep module can be built from small parts; callers just don't see them.
- The deletion test. "Imagine deleting the module. If complexity vanishes, it was a pass-through."
- The interface is the test surface. Callers and tests cross the same seam.
- One adapter means a hypothetical seam. Two adapters means a real one. Don't add a seam unless something varies across it.
It also gives three testability rules with TypeScript examples: accept dependencies instead of creating them, return results instead of producing side effects, and keep the surface small. It rejects Ousterhout's lines-of-code ratio for depth because it "rewards padding the implementation."
What's in the folder:
SKILL.md: the glossary, principles and testability rules.DEEPENING.md: sorts a module's dependencies into four categories (in-process, local-substitutable, remote but owned, true external) and says how to test each, plus "replace, don't layer": delete old unit tests on shallow modules once tests exist at the deepened interface.DESIGN-IT-TWICE.md: when you want alternatives, the agent spawns three or more sub-agents in parallel, each told to produce a radically different interface (minimal, flexible, common-caller, or ports and adapters), then compares them and recommends one.agents/openai.yaml: Codex display metadata ("Codebase Design").
The skill is model-invoked: you can type /codebase-design, or the agent can load it when a design task fits.
How do you install it?
The README gives a plugin route and an editable-files route, and says to pick one per agent so you don't get every skill twice.
Claude Code plugin (whole set, updates itself). The collection is in Anthropic's official plugin marketplace:
claude plugin install mattpocock-skills@claude-plugins-official
Plugin skills are namespaced, so it appears as /mattpocock-skills:codebase-design.
Codex plugin. From the README:
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
Editable files with the skills CLI. The command on skills.sh:
npx skills add https://github.com/mattpocock/skills --skill codebase-design
The skill has no dependencies of its own. Add -g with the skills CLI to install it for all projects. In Claude Code it lands in .claude/skills/codebase-design/, or ~/.claude/skills/codebase-design/ with -g, the standard skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
The MIT license also lets you upload the folder as a ZIP in claude.ai under Customize, then Skills, as described in Anthropic's help article. The design it twice step relies on sub-agents, so it fits a coding agent better.
How do you use it?
Reach for it when you already know which code you're reshaping and need to think about where the seam goes and how small the interface can be. The docs also suggest it for settling an argument about what a design word means.
Example prompts (suggestions, not quotes from the repo):
Use /codebase-design to review the interface of our PaymentsClient. Does it pass the deletion test?Where should the seam go between the order logic and the Stripe calls? Name both adapters.Design the notifications module interface twice: once minimal, once optimized for the common caller.Classify the dependencies of the report generator using the categories in DEEPENING.md.
Signs it's working, from the docs: the conversation stops saying "component", "service" and "boundary"; a proposed seam comes with a second adapter named; and interface talk covers invariants and error modes, not just types.
Requirements: nothing beyond a coding agent. Design it twice needs one that can run sub-agents, such as Claude Code subagents.
Tips and limits
From the repo's docs, not from testing:
- Don't use it as a driver. The docs record an agent that, told to "drive the open decisions" with this skill, worked for a long time redesigning things before asking anything. The fix is a driver skill (
/grill-with-docs,/improve-codebase-architectureor/tdd) that uses codebase-design as vocabulary. The maintainer closed the issue on 6 October 2026 without changing the skill. - It doesn't enforce module boundaries. The most-asked question is how to stop imports reaching past an interface in TypeScript. The skill doesn't answer it; the docs mention options like a monorepo package or a linter such as dependency-cruiser.
- It isn't a folder convention. Replies quoted in the docs say deep modules are about the interface, "no matter what the file system looks like."
- The glossary is small on purpose. Proposals to add terms like connascence were closed as not planned in October 2026.
The skill runs no scripts and writes no files. As of 24 October 2026, skills.sh showed Pass from all three security audits (Gen Agent Trust Hub, Socket and Snyk). Under the MIT License you can copy and change it if you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md along with DEEPENING.md and DESIGN-IT-TWICE.md. For a link to a folder with many skills, it shows a list to pick from. Everything lives in your own private GitHub repo and installs into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Matt Pocock or mattpocock/skills.
Similar skills
- TDD skill: owns the seam you test at, and lists codebase-design as a prerequisite.
- Improve codebase architecture skill: surveys a repo for deepening candidates and writes them in this vocabulary.
- Domain modeling skill: the matching reference for your problem domain's words rather than module shape.
- Grill with docs skill: a driver skill that argues the design with you.