PlugWiki

codebase-design Skill for Claude Code: Design Deep Modules

Gives Claude a shared vocabulary for designing deep modules: lots of behaviour behind a small interface, placed at a clean seam.

Installs
895.5K
on skills.sh
Stars
309.2K
on GitHub
Files
3
besides SKILL.md
Updated
Nov 2026
last repo commit

codebase-design makes the agent talk about code structure in fixed terms: module, interface, depth, seam, adapter, leverage and locality. It tells the agent to use those words exactly and not swap in "component", "service" or "boundary".

It applies when you want to design or improve a module's interface, find places to deepen a module, decide where a seam goes, or make code easier to test. It bundles two guides for going further and no scripts. Other skills in the same repo call on its vocabulary.

Good for

  • Developers reshaping a module so it is easier to test and navigate
  • Teams that want agents and people to use the same design terms
  • Anyone reviewing an architecture for shallow, pass-through modules

Install codebase-design

Claude Code

  1. 1

    Copy this prompt.

    Install the codebase-design skill in Claude Code. Run this command:

npx skills add https://github.com/mattpocock/skills --skill codebase-design

Then check that it loaded and tell me how to use it.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

  1. Glossary
  2. Deep vs shallow
  3. Principles
  4. Designing for testability
  5. Relationships
  6. Rejected framings
  7. Going deeper

Key facts

Author
Matt Pocock
Repo
mattpocock/skills
Installs on skills.sh
895,457 (Nov 2, 2026)
GitHub stars
309,237 (Nov 2, 2026)
License
MIT
Last repo commit
Nov 1, 2026
Files next to SKILL.md
3 files
skills.sh audits
Gen Agent Trust Hub pass, Socket pass, Snyk pass
Bundled guides
DEEPENING.md and DESIGN-IT-TWICE.md

What it includes

  • Defines module, interface, implementation, depth, seam, adapter, leverage, locality

    Glossary

  • Small interface with much behaviour is deep; a big interface over thin code is shallow

    Deep vs shallow

  • If deleting a module makes complexity vanish, it was a pass-through

    Deletion test

  • Pass dependencies in, return results instead of side effects, keep the surface small

    Designing for testability

  • How to deepen a cluster of modules given its dependencies

    Read · DEEPENING.md

  • Runs parallel sub-agents to design an interface several ways, then compares them

    Read · DESIGN-IT-TWICE.md

From the official docs

Questions

What does codebase-design do?

It gives the agent one set of terms for module design and a few rules, such as the deletion test and "one adapter is a hypothetical seam, two is a real one". It changes how the agent reasons and writes about structure.

How do I install codebase-design?

Use the install box at the top. The skill is a single SKILL.md plus two guide files, and it links only to those.

Does it change my code by itself?

The SKILL.md describes vocabulary and principles, not an edit procedure. Code changes come from whatever task you give the agent while it is loaded.

Does it need an API key or scripts?

No key is named, and it bundles no scripts. DESIGN-IT-TWICE.md does ask the agent to run parallel sub-agents.

Is codebase-design safe?

It is text guidance with no bundled scripts. It can lead the agent to restructure code, so review the diff as you would any refactor. Skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass.

How is it different from improve-codebase-architecture?

The ask-matt router describes codebase-design as the vocabulary layer, and improve-codebase-architecture as the skill that surfaces deepening opportunities. Use this one for the terms, the other to hunt for work.

Information

updated Nov 2, 2026

Repository
mattpocock/skills
Folder
skills/engineering/codebase-design

mattpocock/skillsskills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4
  1. codebase-design SKILL.md · github.com
  2. codebase-design on skills.sh · skills.sh
  3. mattpocock/skills README · github.com
  4. ask-matt SKILL.md · github.com

Updated Nov 2, 2026.