arda/skills
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: name the reference skills other skills lean on

Browse source 
codebase-design, domain-modeling and grilling are pulled out as
standalone, model-invoked skills precisely so other skills can point
at them and so you can reach them as a reference independently of the
steps any wrapper mandates. Add a "Pulled out on purpose" section to
each that names who leans on it and why it stands alone, and slim the
overlapping "Where it fits" prose to avoid duplication.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Matt Pocock 2026-07-01 11:27:36 +01:00
parent f5ed5657bd
commit 995fceec7a
3 changed files with 24 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/engineering/codebase-design.md
View file

@ -14,7 +14,7 @@ npx skills update codebase-design
`codebase-design` gives you a shared, precise vocabulary for designing **deep modules** — a lot of behaviour hidden behind a small interface, placed at a clean seam, testable through that interface.
The load-bearing constraint: it is a **language, not a procedure**. It doesn't restructure your code or hand you a refactor plan — it fixes the words (module, interface, depth, seam, adapter, leverage, locality) so that every design conversation and every other skill that touches design speaks the same way. Consistent language is the whole point; "component," "service," "API," and "boundary" are deliberately banned because they blur the distinctions that matter.
It is a **language, not a procedure**. It doesn't restructure your code or hand you a refactor plan — it fixes the words (module, interface, depth, seam, adapter, leverage, locality) so that every design conversation and every other skill that touches design speaks the same way. Consistent language is the whole point; "component," "service," "API," and "boundary" are deliberately banned because they blur the distinctions that matter.
## When to reach for it
@ -32,6 +32,12 @@ Two checks do most of the work. The **deletion test**: imagine deleting the modu
Callers and tests cross the same seam, so a well-placed interface gives tests something durable to aim at while the code underneath moves freely. That's why the vocabulary insists on **seam** (Feathers' term — a place you can change behaviour without editing there) over the overloaded "boundary," and why "interface" here means *every fact a caller must know*: signatures, yes, but also invariants, ordering, error modes, and performance — not just the type-level surface.
## Pulled out on purpose
`codebase-design` is the **single source of truth** for the deep-module vocabulary, split out as its own model-invoked skill so anything can reach it. Other skills point at it rather than restating the words: [tdd](https://aihero.dev/skills-tdd) borrows it to place a seam before writing the test, [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) leans on it while restructuring existing code, and [to-prd](https://aihero.dev/skills-to-prd) speaks it when it sketches seams and deepening opportunities before writing a spec.
The point of keeping it standalone is that you can also reach for it on its own — as a **reference** for how to think about module design — without triggering the larger process any of those skills mandate. Fix the words once, in one place, and every design conversation inherits them.
## Where it fits
`codebase-design` is a **reach-for-it-anytime standalone** and the shared vocabulary layer under the engineering skills — it's the language that [to-prd](https://aihero.dev/skills-to-prd) uses when it sketches seams and deepening opportunities before writing a spec, and that [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) leans on when it restructures existing code. Its closest neighbour is [domain-modeling](https://aihero.dev/skills-domain-modeling), the parallel vocabulary skill for the problem domain rather than the module structure. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.
`codebase-design` is a **reach-for-it-anytime standalone** — the shared vocabulary layer under the engineering skills. Its closest neighbour is [domain-modeling](https://aihero.dev/skills-domain-modeling), the parallel vocabulary skill for the problem domain rather than the module structure. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.