Codebase Design: Deep Module Design Guide
Provides shared vocabulary and principles for designing deep modules, helping define interfaces, improve module design, and enhance testability and navigation.
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.
- 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.
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.
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 do you install this skill?
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).
How do you use this skill?
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.