codebase-design
An agent skill by mattpocock, from mattpocock/skills. Tags: architecture, code-quality, deep-modules, design, typescript.
What it does
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.
Install
With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:
npx skills add mattpocock/skills --skill codebase-designOr copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):
git clone --depth 1 https://github.com/mattpocock/skills
cp -r skills/skills/engineering/codebase-design ~/.claude/skills/codebase-designSafety box score
Grade A, minimal risk: 0 of 100 risk points, rated 2026-10-15. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.
This skill is documentation-only: it teaches a vocabulary and workflow for software design, with no scripts, network calls, or filesystem mutations. The main risk is behavioral rather than technical—it strongly prescribes how the agent should reason and present design options, including parallel sub-agents, but it does not itself reach into the machine or accounts.
| Category | Level | Why |
|---|---|---|
| Code & shell execution | 0 (none) | No shell commands, code execution, or native scripts are shipped; the files are Markdown and a small YAML metadata file only. |
| Network access | 0 (none) | There are no fetches, uploads, or remote API calls; references like Stripe/Twilio are conceptual examples in `DEEPENING.md`, not integrations. |
| Filesystem reach | 0 (none) | The skill describes design concepts only and does not read, write, or delete user files outside the project. |
| Secrets & credentials | 0 (none) | It does not ask for tokens, keys, passwords, `.env` files, or browser/CLI sessions. |
| Privilege & persistence | 0 (none) | No sudo, service installation, shell startup edits, or OS/git configuration changes are requested. |
| Instruction hijack surface | 0 (none) | It is prescriptive about terminology and process (`Use these terms exactly`, `spawn 3+ sub-agents`), but it does not instruct the agent to ignore higher-priority rules, hide actions, or follow untrusted remote instructions. |
| Irreversible actions | 0 (none) | It does not itself send messages, post, pay, deploy, or book anything; the autonomy described is limited to internal design discussion and parallel sub-agents. |
| Transparency | 0 (none) | All shipped content is human-readable Markdown/YAML; there are no binaries, installers, minified blobs, or decoded-at-runtime code. |
Before installing
- Open `SKILL.md`, `DEEPENING.md`, and `DESIGN-IT-TWICE.md` to confirm the package is documentation-only and contains no scripts or remote fetches.
- If your agent runtime supports it, load the skill in a read-only sandbox first and verify it only changes language and planning behavior.
- Confirm you are comfortable with its strong terminology constraints (`module`, `interface`, `seam`, `adapter`) and its request to spawn parallel sub-agents for design exploration.
Rated 2026-10-15 by an automated review of 4 files from the skill's repository.
Source
- Repository
- mattpocock/skills (all skills from this repository)
- Path
- skills/engineering/codebase-design/SKILL.md
- Branch
- main
- Updated
- 2026-10-05
Related skills
- principle-type-system-discipline — Apply when designing types, reviewing a function signature, or writing code in any statically-typed language.
- setup-ts-deep-modules — Wire dependency-cruiser into a TypeScript repo so each package is a deep module.
- typescript-pro — Implements advanced TypeScript type systems, creates custom type guards, utility types, and branded types, and configures tRPC for end-to-end type safety.
- app-platform-designer — Transform natural language application descriptions into production-ready DigitalOcean App Platform specifications.
- architect — Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in.
- audit-context-building — Understand a codebase before looking for bugs in it - what each function assumes, what it guarantees, and what it depends on elsewhere.