Guide · Agent skill
How to use the Codebase Design Vocabulary agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Codebase Design Vocabulary skill (skill name: codebase-design) teaches an AI agent a fixed set of software design terms, such as module, interface, seam, depth, leverage and locality, and asks it to reason with them when you restructure code. It is aimed at developers who are reorganising a messy codebase, making code easier to test, or comparing interface designs before writing them. By the end of this guide you will know what the skill changes, how to install it, how to phrase requests so the agent picks it up, and what to watch for.
Codebase Design Vocabularymattpocock/skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the codebase-design ZIP file from this skill's page on the directory.
- 2Unzip into a skills folder. Unzip the file into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder for a single project.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- 4Name the module you want reviewed. Point the agent at a specific file, class or folder so it has concrete code to analyse.
- 5Ask a natural design question. Use phrases like improve this module's interface, find deepening opportunities, or make this easier to test.
- 6Request alternatives if needed. Ask for alternative interface designs to compare on depth, locality and seam placement before writing code.
What the skill makes the agent do
Once installed, the agent uses a specific design vocabulary when it reviews or plans code structure. The core aim is a deep module: a lot of behaviour behind a small interface, placed at a clean seam, and testable through that interface.
The skill defines terms and asks the agent to use them exactly. It tells the agent not to substitute words like component, service, API or boundary, so its answers stay consistent from one review to the next.
- Module: anything with an interface and an implementation, such as a function, class, package or slice.
- Interface: everything a caller must know to use the module correctly, including invariants, ordering, error modes, required configuration and performance characteristics.
- Seam: the location where a module's interface lives, and a separate design decision from what sits behind it.
- Depth, leverage and locality: how much behaviour sits behind an interface, what callers gain from that, and what maintainers gain from changes concentrating in one place.
- Deletion test: imagine removing a module; if complexity vanishes it was a pass-through, and if it reappears across callers it was earning its keep.
Install the codebase-design skill
Download the ZIP file from the skill's page on this directory and unzip it. You can install it for yourself across all projects, or for a single project.
For all your projects, place the unzipped skill folder in ~/.claude/skills/. For one project, place it in that project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/
- Project install: the .claude/skills/ folder inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the skill
Trigger the skill with natural requests
You do not need a special command. The skill's description lists the situations where it applies, so phrase your request around one of them: designing or improving a module's interface, finding deepening opportunities, deciding where a seam goes, or making code more testable or easier for AI to navigate.
Be specific about the module or area you care about. Naming the file, class or folder gives the agent something concrete to analyse.
- "Review the interface of the OrderService module in src/orders and tell me if it is shallow."
- "Where would a seam make the payments code easier to test?"
- "Find places in the billing folder where we could deepen modules."
- "Help me make the upload pipeline easier for an AI agent to navigate."
Use the companion guides for deeper work
The main skill points to two companion guides. DEEPENING.md covers deepening a cluster of code given its dependencies. It classifies dependencies into categories, such as in-process, local-substitutable, and remote but owned, and explains how each category affects testing across the seam.
DESIGN-IT-TWICE.md covers exploring alternative interfaces. The agent frames the problem space, then spins up parallel sub-agents to design the interface several radically different ways, and compares them on depth, locality and seam placement. Ask for this when you want options before writing code.
- Ask for DEEPENING-style work when you have a candidate cluster and want to know how to test it across its dependencies.
- Ask for alternatives when you want to compare several interface designs before committing to one.
Know what it needs and what it does not do
The skill lists no required tools or prerequisites. It does not run scripts and does not use the network, so it only shapes the agent's reasoning and suggestions. The skill is written for readers who already know software architecture, because the agent will use those terms in its answers.
The skill is not a replacement for reading your code or running your tests. Treat its suggestions as a design review to check against the actual codebase.
- Requires: nothing listed in the source
- Runs scripts: no
- Uses network: no
- Licence: MIT
Tips for getting useful results
The vocabulary is most useful on code with real structure to reason about. Pick modules that have several callers or tests, because the deletion test and leverage ideas depend on how many places use an interface.
Avoid the skill for small one-off scripts or simple bug fixes, where the vocabulary adds overhead without much benefit.
- Give the agent the callers and tests along with the module, so it can judge leverage.
- Ask it to explain its reasoning in the skill's terms, then check each claim against the code.
- Use it before a refactor to agree on where the seam should go, not after the code is already written.
What people use it for
- Reviewing a module's interface to check whether it is shallow and could hide more behaviour.
- Deciding where a seam should go so tests can run through a stable interface.
- Planning how to deepen a cluster of related code, given whether its dependencies are in-process, local or remote.
- Comparing several radically different interface designs before committing to one.
- Making a tangled part of a codebase easier for AI agents to navigate.
Frequently asked questions
How do I install the codebase-design agent skill?
Download the ZIP from the skill's page and unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.
Does the codebase-design skill require anything else to run?
The source lists no required tools or prerequisites. It does not run scripts and does not use the network, so it only changes how the agent reasons about code structure.
Is the codebase-design skill free?
The skill is released under the MIT licence, as stated on its page. The source does not mention any price.
Is this skill suitable for beginners?
It is written for developers who already know software architecture terms, since the agent uses them in its answers. Non-developers and people writing small one-off scripts will likely find it adds overhead without much benefit.
What is the difference between this skill and asking an agent to refactor?
This skill makes the agent use a fixed vocabulary of modules, interfaces, seams, depth, leverage and locality, and aim for small interfaces that hide much behaviour. Without it, the agent's terms and goals may vary between answers.
Why won't the skill trigger when I ask about my code?
The skill applies to design-focused requests, such as improving a module's interface, finding deepening opportunities, placing a seam, or making code more testable. Phrase your request around one of those goals and name the specific module or folder.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a developer restructuring code, making it easier to test, or comparing interface designs, and you want consistent design reasoning from your agent. Skip it for small scripts, simple bug fixes, or if you are not comfortable with software architecture terms, since the agent will use them throughout its answers.
Download the skill