software-design-document
Generate detailed software design documents from an existing L1/L2 requirements set. Use this skill whenever the user wants to produce design docs, detailed designs, a software design document (SDD), architecture documentation, or per-feature / per-subsystem design write-ups — especially when they mention a docs/specs folder, L1/L2 requirements, C4 diagrams, PlantUML, sequence or class diagrams, vertical slices, or a docs/detailed-designs folder. Trigger this even when the user only says "document the design", "write up the architecture", "turn these requirements into designs", or "create the detailed designs" without naming the format. The skill scaffolds docs/detailed-designs/{subsystem}/{feature}/ with a README written in a strict house style, plus rendered C4, class, and sequence diagrams shown inline.
- License 许可
- MIT
- 最近更新
- 2026-10-19
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- software-design-document
- description
- Generate detailed software design documents from an existing L1/L2 requirements set. Use this skill whenever the user wants to produce design docs, detailed designs, a software design document (SDD), architecture documentation, or per-feature / per-subsystem design write-ups — especially when they mention a docs/specs folder, L1/L2 requirements, C4 diagrams, PlantUML, sequence or class diagrams, vertical slices, or a docs/detailed-designs folder. Trigger this even when the user only says "document the design", "write up the architecture", "turn these requirements into designs", or "create the detailed designs" without naming the format. The skill scaffolds docs/detailed-designs/{subsystem}/{feature}/ with a README written in a strict house style, plus rendered C4, class, and sequence diagrams shown inline.
02 资源文件 5
- 参考文档evals/evals.json5.7 KB
- 参考文档references/diagrams.md10.2 KB
- 参考文档references/example-design.md5.1 KB
- 参考文档references/writing-style.md5.1 KB
- 脚本scripts/render_puml.py4.8 KB
03 SKILL.md 正文
Software design document
This skill turns a set of requirements into a browsable tree of detailed feature designs. The output is deterministic in shape, so a reader always knows where to look:
docs/detailed-designs/
└── {subsystem}/
└── {feature}/
├── README.md detailed design (renders on GitHub, images inline)
└── diagrams/
├── *.puml PlantUML sources
└── *.png rendered images the README links to
The design is written against requirements — every feature traces back to level-2 (L2) requirements, which in turn refine level-1 (L1) requirements. That traceability is the reason for the requirements gate below: without L1/L2 requirements there is nothing to design against, and inventing them would defeat the purpose.
Read the three references as you reach the steps that need them:
references/writing-style.md— the house voice every README uses.references/diagrams.md— PlantUML templates for C4, class, and sequence.references/example-design.md— a complete finished feature to imitate.
Step 0 — Requirements gate (do this first, every time)
A detailed design is a refinement of requirements. If the requirements are not present, stop and ask for them rather than fabricating a design that traces to nothing.
Check for a docs/specs/ folder (relative to the repo root) that contains
markdown holding both L1 and L2 requirements. Detect this by searching the
markdown for requirement identifiers at both levels. The level token (L1/L2)
and the domain appear in either order, and a single spec set may mix the
two conventions — treat both as valid:
- level-first:
L1-<DOMAIN>-<n>,L2-<DOMAIN>-<n>— e.g.L1-INTAKE-001,L2-CONSENT-002 - domain-first:
<DOMAIN>-L1-<n>,<DOMAIN>-L2-<n>— e.g.INTAKE-L1-001,CONSENT-L2-002
Sections or tables clearly labelled L1 and L2 also count. This regex catches both orderings:
ls docs/specs 2>/dev/null && grep -rroE "(L[12]-[A-Z]+|[A-Z]+-L[12])-[0-9]+" docs/specs | sort -u | head
When you read an identifier, parse the level (does it contain L1 or L2?)
and the domain (the alphabetic segment on the other side of the level token)
independently of their order — L2-INTAKE-002 and INTAKE-L2-002 denote the
same level and domain. Keep each identifier exactly as the spec writes it;
never rewrite one convention into the other.
If docs/specs/ is missing, has no markdown, or shows no recognizable L1 and
L2 requirements: stop and tell the user. Say plainly what is needed — a
docs/specs/ folder of markdown requirements at levels L1 and L2, each with an
identifier and L2 tracing to its parent L1 — and do not scaffold anything or
invent requirements. This is the one hard stop in the workflow.
Step 1 — Identify the subsystems
Think of the system as a small number of subsystems (bounded contexts / major capability areas).
- If
docs/specs/already has one folder per subsystem, reuse those names exactly. The specs are the source of truth for naming; matching them keeps the two trees aligned and lets a reader move between spec and design without translating names. - Otherwise, infer the subsystems from the specs. The domain segment of the
requirement IDs is a strong signal (
INTAKE,CONSENT,NFR, …) — it is the alphabetic segment of the identifier, on whichever side of theL1/L2token it sits (L2-INTAKE-002andINTAKE-L2-002both have domainINTAKE). Headings and grouping in the spec markdown are further signals. Group related requirements into named subsystems.
Step 2 — Slice each subsystem into vertical features
Within a subsystem, split the work into vertically sliced features. A vertical slice is one user-facing capability that cuts through every layer it needs — UI → API → application/domain → data — rather than a horizontal layer shared across capabilities. "Decline an application" is a vertical slice; "the repository layer" is not.
Good slices map cleanly onto one or a few L2 requirements and can be described,
diagrammed, and reasoned about on their own. Name each slice as a short verb
phrase (decline-application, record-consent, submit-application).
Step 3 — Scaffold the folders
For each subsystem and each of its features, create:
docs/detailed-designs/{subsystem}/{feature}/diagrams/
Use the subsystem naming from Step 1 and kebab-case feature names from Step 2.
Step 4 — Write each feature's README.md
The detailed-design file is the feature folder's README.md — GitHub renders
it automatically and shows the diagram images inline. Use exactly these four
headings, in this order, and write all prose in the house voice
(references/writing-style.md). references/example-design.md shows a complete,
finished target — imitate its shape.
Overview
Background, assuming the reader knows nothing. Explain what the feature is, why it exists, where it sits in the subsystem, and define every local domain term at first use. A newcomer should be able to read only this section and understand what the feature is for.
Description
The concrete building blocks of the slice: the components, types, functions, and
classes involved, and what each one does. If the codebase already contains these,
inspect the source and describe what is really there, using the real names. If
the feature is greenfield, describe the components the design introduces. Where a
detail is genuinely undecided, mark it <TO SUPPLY> rather than guessing.
Requirements
List only L2 requirements — no L1 specs stand on their own here. Present them as a table of the L2 identifier, the L1 identifier it refines, and the requirement text:
| L2 ID | Refines (L1) | Requirement |
|-------|--------------|-------------|
| `L2-INTAKE-002` | `L1-INTAKE-001` | The system shall record a decline decision with a reason. |
Pull the exact text and IDs from docs/specs/; keep requirement wording in the
shall/should/may form. Copy each identifier verbatim in whatever convention
the spec uses — if the specs write INTAKE-L2-002 / INTAKE-L1-001, the table
cells read INTAKE-L2-002 and INTAKE-L1-001, not a reordered form. Consistency
with the source of truth matters more than a uniform house ordering, so that
every id in the design still resolves back to a real line in the specs.
Diagrams
Embed the rendered diagrams with a one- or two-sentence prose lead-in before each
(the prose introduces and interprets the picture; no significant fact should live
only inside an image). Reference the .png, with a relative path, so it shows
inline:

Include, per feature: the C4 diagrams (context, container, component), a class diagram (structure + relationships), and a sequence diagram per behaviour.
Step 5 — Author the diagrams
Write a .puml per diagram into the feature's diagrams/ folder, following
references/diagrams.md. The essentials:
- C4 uses the offline standard library:
!include <C4/C4_Context>,<C4/C4_Container>,<C4/C4_Component>. Build the diagram from the C4 macros that include defines —Person(...),System(...),Container(...),Component(...), the*_Boundary(...) { }blocks, andRel(...)for every relationship. Never draw rawrectangle/componentshapes or barea --> barrows inside a C4 diagram; that discards the styling and semantics the include exists to give. Scope each diagram to what the feature touches. - Class diagrams show fields, methods, and typed relationships (association, dependency, inheritance, composition).
- Sequence diagrams show behaviour with
boxgroupings that separate Frontend from Backend and name the specific application/layer, coloured by tier. The sequence template inreferences/diagrams.mdis the gold standard; match its skin and box structure. Trace steps to requirement IDs in the message text where a step enforces one.
Step 6 — Render every diagram to PNG
The README links to .png files, so each .puml must have a rendered sibling.
Render the whole tree with the bundled script (it locates plantuml.jar or
plantuml on PATH and writes each .png next to its source):
python <skill>/scripts/render_puml.py docs/detailed-designs
A non-zero exit means at least one diagram failed to render — an image the README
points at does not exist. Read the reported error, fix the .puml, and re-run
until the exit is clean. (Equivalent direct call if needed:
java -jar $PLANTUML_JAR -tpng docs/detailed-designs/**/diagrams/*.puml.)
Step 7 — Verify before finishing
- Every
.pumlhas a.png— the render step exited clean. - Every image link resolves — each
in a README points to a file that exists. - C4 diagrams use the C4 macros — each C4
.pumlincludes a<C4/...>header and is composed ofPerson/System/Container/Component/Rel(and boundary) macro calls, with no rawrectangle/component/nodeshapes or bare arrows standing in for them. - Requirements are L2-only, each with its L1 parent and exact text from the specs.
- Prose passes the house-style self-check in
references/writing-style.md(nowe/you, obligation only viashall/should/may, no hype or fillers, gaps marked<TO SUPPLY>not invented).
Quality bar
A finished design tree lets a reader open any feature folder on GitHub and see a self-contained page: plain-language background, the concrete parts, the L2 requirements it satisfies, and diagrams that render inline — all in one steady voice, every claim tracing to a requirement or marked as an open question.
04 同仓库更多 Skills
writing-screen-composition
Create or update docs/screen-composition.md, a document that itemizes every page, dialog, notification and shell part from the HTML mocks and lists, for each, the component-library components it shall be composed of plus the UI that must be built locally. Also ensures AGENTS.md has the "Components library is mandatory (CRITICAL)" section. Use when the user mentions screen composition, which components a page uses, mapping mocks to a component library, local vs library UI, or before implementing an application against a component library; and whenever docs/mocks and a component catalogue exist but docs/screen-composition.md does not or is out of date.
writing-requirements
Create and manage software requirements documents (L1 high-level and L2 detailed with acceptance criteria) in docs/specs/. Use this skill whenever the user mentions requirements, specs, specifications, user stories, features to build, acceptance criteria, ATDD, or wants to define what a system should do before coding. Also use when the user says things like 'what should we build', 'let's plan the feature', 'write up what this needs to do', 'define the behavior', or describes functionality they want implemented -- even if they don't explicitly say 'requirements'. If the user is about to start coding a feature and there are no requirements yet, proactively suggest using this skill first. Requirements come before code. Always.
writing-html-mocks
Write static HTML mocks in docs/mocks/ for EVERY page, dialog and notification of a product in EVERY state (default, loading, empty, error, invalid, busy, success, no-results, forbidden, stacked...), responsive, light and dark, keyboard-accessible, with real copy and a coverage matrix. Use this skill BEFORE writing any frontend code, component, template, view or page; whenever the user says mock, mockup, wireframe, prototype, UI, UX, screen, layout, dialog, modal, toast, banner, empty/error/loading state, "what should this look like", "show me the UI", or describes a feature with a visible result; and whenever docs/specs or docs/detailed-designs exist but docs/mocks does not. Also use it to add missing states to existing mocks. Mocks come before implementation: if asked for frontend code with no mocks, say so and offer this first. Pair with extracting-design-systems to turn finished mocks into docs/design-system/.
writing-feature-prompts
Write a ready-to-run implementation prompt for a feature request or a bug fix in the current repository, save it outside the repository and open it in a text editor (Notepad on Windows). A feature prompt drives mocks, design system, requirements, detailed design, estimate update and incremental acceptance-test-driven implementation end to end without stopping; a bug-fix prompt drives reproduce, root cause, fix and documentation alignment. Use whenever the user asks to "create a prompt", "write a prompt for this feature" or "for this bug", wants a "prompt to build X" or "prompt to fix Y", or asks to open a prompt in Notepad.
writing-design-documents
Create software design documents and architecture write-ups from existing L1/L2 requirements in docs/specs/. Use for detailed designs organized by subsystem and feature, with requirement traceability and rendered PlantUML C4, class, and sequence diagrams in docs/detailed-designs/.
writing-agent-instructions
Writes the agent instruction files a repository needs so coding agents know how to work in it - AGENTS.md plus the CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md pointers - generated from a description of what the project shall be, for a project that does not exist yet. Use this whenever someone mentions AGENTS.md, CLAUDE.md, GEMINI.md, copilot-instructions, "agent instructions", "agent context files", "coding agent guidance", or asks to set up, scaffold, bootstrap, or initialise the conventions for a new project or repository. Use it too when someone describes a project they are about to start and wants an agent to follow its conventions, even if they never name any of these files - if they are standing at an empty directory describing what they intend to build, this is the skill.