The Catalogue¶
Every skill, what it owns, and — just as importantly — what it does not own. The second column is the one to read when two skills seem to overlap.
Which skill owns what¶
Adjacent concerns are deliberately separated so that only one skill fires on a given question.
| Question | Skill |
|---|---|
| Should this be its own service? | service-boundaries |
| Which layer does this class belong in? | clean-architecture |
| Is this an entity or a value object? What is the aggregate? | domain-modelling |
| Why is this query slow? How do I write this migration? | data-access |
| Should reads come from a projection? How stale may it be? | cqrs-and-consistency |
| What fields does this endpoint return? Is this change breaking? | api-contracts |
| REST, GraphQL, gRPC, or WebSocket? | api-protocols |
| How do I wrap this vendor SDK? Where does the mapping go? | infrastructure-adapters |
| What happens when this call times out? | resilience-patterns |
| What happens if this runs twice? Should this type be immutable? | idempotency-and-immutability |
| Can this caller access this record? | secure-service |
| At which level should I test this? | test-strategy |
| Will my release break a consumer? | contract-testing |
| Where does this setting live? Should I add this library? | config-and-dependencies |
| What should we agree before writing code? | design-first |
| Two answers are both defensible — now what? | collaborative-judgment |
Frequently confused pairs¶
service-boundaries vs clean-architecture — boundaries between services, versus structure
inside one. Services named api, business-logic, data-access are a layering diagram that
escaped into deployment.
domain-modelling vs data-access — what the types mean, versus how they are stored and
fetched. An aggregate boundary is domain-modelling; the N+1 loading it is data-access.
data-access vs cqrs-and-consistency — one query's correctness and speed, versus whether the
read path should be separate at all and how far it may lag.
api-contracts vs api-protocols — what crosses the boundary (fields, errors, versioning,
compatibility), versus how it travels (protocol choice, and each protocol's own pitfalls).
clean-architecture vs infrastructure-adapters — the layering rule that ports point inward,
versus the craft of actually writing the adapter that implements one.
resilience-patterns vs idempotency-and-immutability — the retry, the breaker, the outbox
mechanism, versus whether the operation was safe to repeat in the first place. Adding a retry to a
non-idempotent write is the failure both of them are trying to prevent, from opposite directions.
test-strategy vs contract-testing — proving behaviour inside one service, versus proving two
services still agree. A contract test that asserts business logic has become the wrong kind of test.
Principles at a glance¶
Each principle's SKILL.md contains its Config Resolution, checklist, anti-pattern scan, and
ambiguity signals. The depth lives in references/defaults.md, loaded on demand.
| Skill | Checklist covers | Depth in references |
|---|---|---|
service-boundaries |
Business capability naming, ubiquitous language, single-writer ownership, autonomy, change coupling, chattiness, transaction fit, team fit, justified split | Finding a boundary from language and change; modular-monolith-first; context mapping patterns; data ownership per field; strangler-fig extraction; sizing |
clean-architecture |
Layer placement, dependency direction, framework isolation, ports owned inward, SOLID at both scales, testability without I/O, pattern justification | The four layers and what goes where; SOLID at class and service level; choosing a pattern from a named force; DI rules; enforcing with architecture tests |
domain-modelling |
Named invariant, valid on construction, behaviour with data, entity vs value, immutable values, primitive obsession, aggregate size, encapsulation, ubiquitous language, illegal states | The building blocks; value objects first; aggregates as consistency boundaries; domain events; making illegal states unrepresentable; when a rich model is the wrong answer |
data-access |
Domain types returned, whole aggregates, explicit transaction boundary, no I/O in a transaction, no N+1, bounded and indexed queries, concurrency, lock order, keyset pagination, migration compatibility, cache invalidation, pool sizing | Repositories; transactions and isolation; optimistic vs pessimistic locking; query performance; connection pools; caching; expand-migrate-contract |
cqrs-and-consistency |
Level justified, smallest step, staleness budget, read-your-writes, rebuildable, idempotent projection, poison events, versioning, single ownership, copy vs replica | The five levels; projections; read-your-writes strategies; event sourcing honestly; ownership and copies; stating consistency in the contract |
api-contracts |
Spec first, consumer-shaped, backward compatible, errors specified, idempotency, bounded collections, explicit types, no internal leakage, events as facts, compatibility mode | Specification formats; modelling operations; pagination; the error catalogue; idempotency keys; evolution rules; event envelopes and registry modes |
api-protocols |
Shape fits, estate consistency, reachability, REST verb semantics, GraphQL limits and batching and field authorisation, gRPC deadlines and evolution, push reconnection, heartbeats, backpressure, observability | Choosing from the interaction shape; REST cache semantics; GraphQL's two failure modes; gRPC message evolution; WebSocket and SSE design order |
infrastructure-adapters |
Port owned inward and domain-shaped, vendor types contained, failures translated, no business rules, resilience here only, explicit tested mapping, tolerant reader, untrusted input, injected clock, observable, tested at the wire | Port design; what belongs in an adapter; wrapping an SDK; mapping; adapter shapes per integration type; testing adapters; adapters and a service mesh |
resilience-patterns |
Timeout, deadline propagation, retry safety and shape and classification, no nested retries, circuit breaker, isolation, fallback, idempotent consumer, no dual write, compensation, correct probes | Timeouts; retry with full jitter and budgets; breaker states and thresholds; bulkheads and shedding; fallbacks; the outbox and inbox; sagas; probes; library equivalents |
idempotency-and-immutability |
Repeat safe, mechanism named, key scoped and retained, atomic dedup, idempotent consumer, side effects counted, job safety, idempotent compensation, immutable values, no leaked mutable state, safe publication | Why repeatability is not optional; four ways to be idempotent; idempotency keys; idempotent consumers; non-database side effects; jobs; immutability; where mutability is right; append-only history |
secure-service |
Authenticated, object- and function-level authorisation, deny by default, input validation, injection safety, mass assignment, SSRF, external secrets, clean output and logs, transport, sensitive-flow limits, dependency integrity | The API Top 10 as checks; authentication and service identity; input, injection and output; secrets; personal data; supply chain; cheap threat modelling |
test-strategy |
Right level, behaviour not implementation, one reason to fail, naming, AAA, determinism, isolation, no sleep, justified doubles, real assertions, failure paths, fails-first | The portfolio and what each level must not own; component tests in detail; test doubles; determinism causes and fixes; structure and naming; test data; coverage honestly |
contract-testing |
Consumer driven, only what is used, types not values, provider states, no business logic, both sides run, real verification, deploy gated, messages covered, versioned by commit, failure paths | The full flow; writing the consumer side; provider verification; message and event contracts; versioning with branches and environments; the four variants; what contract tests are not |
config-and-dependencies |
Varies per deployment, not a secret, validated at startup, typed at the edge, no environment branching, documented, safe defaults, flag has an end and defaults off, dependency justified, pinned and locked, upgrade path, shared-library discipline | What is configuration; the rules; environment parity and drift; feature flags; choosing a dependency; versions, locks and updates; internal shared libraries |
design-first |
One level per message, questions over assertions, unknowns named, grounded, decisions surfaced, recorded, gate stated, no code | Depth calibration; question banks per level; gate discipline; the blueprint document; what "no code" means at L4 |
collaborative-judgment |
Genuine, bounded, concrete, consequenced, reversibility marked, recommended, answerable, recorded | The presentation format; reversibility and how much ceremony a decision deserves; recurring microservices trade-offs; recording decisions; handling the answer |
Workflows¶
| Skill | Gates | Produces |
|---|---|---|
/design-service |
Depth agreed before starting; one approval per design level | .msskills/designs/<feature>.md with status: approved |
/implement-service |
Approved blueprint required; plan agreed before code; review mode chosen; any deviation stops the work | Code and tests, layer by layer, each validated before presentation |
/review-service |
Scope stated before starting; each finding verified against a concrete failure | Severity-ranked findings with file, line, and the principle violated |
/refactor-safely |
Named force required; behaviour pinned before any change; green between every step | Restructured code with behaviour provably unchanged |
Profile¶
| Skill | Produces |
|---|---|
/stack-profile |
.msskills/stack.md and a starter .msskills/config.yaml |
Agent¶
| Agent | Used by |
|---|---|
microservice-reviewer |
/review-service, for an independent pass with no memory of having written the code. Read-only |
Not yet covered¶
Deliberate gaps, in rough priority order for future contributions:
observability— OpenTelemetry, correlation propagation, RED/USE, SLOs and error budgets, cardinality discipline. Currently only touched in passing byresilience-patternsandinfrastructure-adapters.deployment-and-release— blue/green, canary, rollback, and the migration compatibility window. Partly covered bydata-accessandconfig-and-dependencies.clean-code— function-level craft. Deliberately omitted so far because the existing skills cover the distributed-system-specific failures, and general clean code is well served elsewhere.incident-to-fixandproduction-readiness-reviewworkflows.
See CONTRIBUTING.md if you want to write one.