| name | cmk:system-design |
| description | This skill should be used when the user asks to "how should we build this", "design the backend", "update the architecture", "draft a system design", or discusses architecture decisions, tech stack changes, infrastructure layout, or scaling strategy. Covers drafting, refining, or updating system design documents covering architecture, tech stack, components, and cross-cutting concerns. |
| version | 0.1.0 |
System Design
Create or iterate system design documents covering architecture, tech stack, components, and cross-cutting concerns. Captures the technical "how" at architecture level. Product requirements belong in the PRD; implementation detail in feature specs. System-wide decisions should reference or create ADRs.
References
Read references/system-design-conventions.md for placement rules and references/system-design-template.md for section structure.
Input
Synthesize from whatever the user provides: conversation context, existing PRD (docs/PRD.md), local docs, external links, direct prompts, or docs/knowledge/ entries (when explicitly referenced).
Workflow: Create
- Normalize input into architecture context: mission, design principles, tech stack, components, dependencies, cross-cutting concerns, constraints.
- Map into template sections from
references/system-design-template.md. Align to local convention if one exists.
- Place at the repository's existing path, or fallback:
docs/system-design.md.
- Mark unknowns in
Open Points — don't guess.
- Link upstream PRD in
Related Documents when one exists.
- Set status to
draft.
Workflow: Iterate
- Read the existing system design in full.
- Upstream check: If
docs/PRD.md exists, scan its scope, success criteria, and status. Warn the user if the update conflicts with upstream PRD.
- Identify what changed and why.
- Update affected sections in place. Preserve unchanged content.
- Update
Last updated date.
- Transition status when appropriate:
draft → active → shipped, or any → deprecated.
Output
- Create: complete system design at
docs/system-design.md
- Iterate: targeted updates to affected sections only
- Unresolved decisions go in
Open Points
- Design principles are opinionated and system-specific
- Architecture diagram matches component descriptions
- Security section is always present — includes assumptions, gaps, and controls
- No feature-level implementation detail
