Individual skill

codebase-design

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, AI-navigable, or agent-legible, choose which invariants to enforce mechanically, or when another skill needs the deep-module vocabulary.

skills/codebase-design/SKILL.md

Read pinned source

Source commit d9d87d04cd9b932469c488a1de79b3260e7435c8

What was checked

Matches the observed repository HEAD: Yes
Scanner rules are current: Yes
Repository scan complete: No
Skill scan complete: Yes
Observed behavior: Instructions only
Last checked: Nov 11, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings): 104
Repository last updated: Nov 9, 2026
License: MIT

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

agent-skills Repository topic
ai-agents Repository topic
design Derived category

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files

SKILL.mdcore · 8,371 bytes
agents/openai.yamlasset · 147 bytes
references/AGENT-LEGIBILITY.mddoc · 4,953 bytes
references/DEEPENING.mddoc · 3,099 bytes
references/DESIGN-IT-TWICE.mddoc · 2,784 bytes

Read excerpt


# Codebase Design

Design **deep modules**: substantial behaviour behind a small interface at a clean seam, testable through that
interface. Use this vocabulary when it clarifies a design decision. The aim is leverage for callers, locality for
maintainers, and testability.

## Glossary

Use these terms consistently where their distinctions matter.

**Module**: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package,
or tier-spanning slice. _Avoid_: unit, component, service.

**Interface**: everything a caller must know to use the module correctly: the type signature, but also invariants,