What does this skill do, and when should you use it?
This is a model-invoked skill for software engineers, offering a shared language for designing deep modules. It defines core terms like module, interface, implementation, depth, and seam, contrasts deep vs shallow modules, and provides design principles and testability guidance. The skill is purely conceptual—it doesn't execute commands—but serves as a reference framework for design decisions. It's useful when defining interfaces, finding deepening opportunities, deciding seam placement, or making code more testable.
Provides a glossary requiring precise vocabulary (module, interface, depth, etc.); shows ASCII diagrams of deep vs shallow modules; lists design principles (deletion test, interface as test surface); offers testability design tips (accept dependencies, return results, small surface area); explains relationships between module, interface, depth, seam, adapter; clarifies rejected framings (e.g., depth as line-count ratio).
- When designing or improving a module's interface, use this skill to align on terminology and principles.
- When scanning a codebase for deepening opportunities, apply the deletion test and depth definition to evaluate modules.
- When deciding where to place a seam, reference the seam definition and adapter principles.
- When writing unit tests, adjust module interfaces based on the skill's testability suggestions.
- When other skills need deep-module vocabulary, this skill serves as the shared language foundation.
How do you install this skill?
- The skill is conceptual; actual implementation effects require user verification.
- Lack of explicit failure handling and boundary definitions may lead to misuse in complex codebases.
- Assumes familiarity with Ousterhout's deep-module theory; novices may struggle.
- The repo contains other skills, but this skill lacks an independent version or changelog, complicating maintenance tracking.
This skill lives in the mattpocock/skills repo under skills/engineering/codebase-design/. Install the whole collection via skills.sh: npx skills@latest add mattpocock/skills, or as a Claude Code plugin (/plugin marketplace add mattpocock/skills).
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/mattpocock/skills.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/engineering/codebase-design" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- How deep is this module?
Place the skill directory in your agent's skills folder or enable it in any Agent Skills–compatible client. When designing or reviewing code, reference the skill's terms and principles, e.g., ask 'How deep is this module?' in conversation. The skill provides no commands; apply it to concrete design tasks.
What are this skill's strengths and limitations?
- Provides precise vocabulary, reducing communication ambiguity.
- Based on established software design principles (e.g., deep modules).
- Scale-agnostic, applicable from functions to system slices.
- Emphasizes testability and navigability, highly practical.
- No attached tests or examples; concepts require self-validation.
- Only offers a framework, not automated evaluation; needs human application.
- Terminology may conflict with existing workflows, requiring adaptation.
- Some principles (like deletion test) rely on judgment and may not fit every scenario.
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Codebase Design: Deep Module Design Guide this page | 57 · Use with care | ★ 281k | 3d ago | MIT |
| cmux Architecture Skill | 63 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| Context Governance ✓ OpenAI · Official | 35 · Not recommended | ★ 128k | 3d ago | Apache-2.0 |
| Overkill — Architecture Exploration Beyond the Pragmatic Answer | 60 · Recommended | ★ 33 | 4mo ago | MIT |
| Agents Best Practices | 61 · Recommended | ★ 2.4k | 6d ago | MIT |
How did FollowSkills review this skill?
The skill provides only a conceptual framework and design principles; it does not execute external operations, handle sensitive data, or produce irreversible side effects, so trust risk is low. No permission overreach or covert behavior identified. However, the skill lacks explicit user confirmation or rollback mechanisms (though it is advisory by nature), and source attribution is not verifiable, so some points are deducted.
The instructions are self-consistent at a textual level, the glossary is clear, and the process descriptions are reasonable; reproducibility depends on user adherence. However, no test suite or automated verification is provided, and key execution paths on real codebases are unverified; handling of abnormal input (e.g., no dependencies) lacks explicit guidance, and failure feedback is not defined. Given static review, only partial marks.
The skill fits scenarios such as designing or improving module interfaces, finding deepening opportunities, and deciding seam placement, with clear target audience (software engineers). But capability boundaries and non-fit cases are only partially articulated (e.g., when not to use it), and trigger conditions rely on user judgment without explicit gating. Environment fit regarding Chinese language support or mainland-China reachability is not considered, but core function does not depend on unreachable overseas services, so a moderate score.
Documentation is well-structured with glossary, principles, examples (code blocks), and pointers for further reading. MIT license present, versioning indicated in repository and package.json, but the skill itself lacks a declared independent version or changelog. Maintenance responsibility is attributed to the author, and update path is via automated releases. However, FAQ and explicit known-limitations disclosure are missing, so a moderate score.
The framework and processes are clear and guide the user to complete module design improvements, but output is advisory rather than directly usable code or files, requiring user application. Marginal value is evident (avoids reinventing concepts), but cost-benefit is not quantified. Static review cannot verify actual effectiveness, so a moderate score.
The skill is based on external principles like Ousterhout, but provides no verifiable tests or case studies. The repository has CI workflows, but they do not exercise the skill's key paths. Thus only minimal auditable material exists, yielding a low score.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →