01
It starts by itself
design doc pull request. Runs in GitHub Actions.
- ↻ design doc pull request
pull_request adds or changes a design doc
riekelt · 17K installsWriting Design Docs skill
Runs by itself, design doc pull request.
Specs reach reviewers without vague gaps.
Install the Writing Design Docs skill and make it a habit: follow https://gethabit.dev/skills/riekelt/writing-design-docs.md
- 1Copy
- 2Paste into Claude Code, Codex or Cursor
- 3It runs by itself
17K installs31 starsMIT licenceSource on GitHub ↗
Writing Design Docs
by riekelt · 17K installs
The skill
The writing design docs skill gives a proposal skeleton, a Why & What decision box and completeness checks, for engineers writing RFCs, specs, design documents or migration plans that argue for a change.
Only when you ask.
The habit
Specs reach reviewers without vague gaps.
↻ Runs by itselfdesign doc pull request
How the habit works.
You don't have to.
When does it start? How does it check its work? What does it remember?
One run, step by step.
Then it stops.
Stops after one document per run, with at most 1 recheck.
- 01
Load background
The agent reads the technical-writing skill first.
- 02
Check the skeleton
The summary must give the conclusion and the chapters must be numbered.
- 03
Check choices
Each contested choice needs a Why & What box with a real alternative and its strongest argument.
- 04
Check costs
The benefits chapter must end with what the change costs.
- 05
Run completeness
It scans for the five vagueness defects before the spec goes to a reviewer.
- 06
Mark sources
Facts without a source get a source wanted marker, never an invented citation.
- 07
Update the board
Open questions and their owners go on the board.
What it may do.
Nothing more.
It writes only in its own folder and asks you before anything goes out.
- Writes only inloops/design-doc-check-loop/**
- Talks tono outside service
- Sendsnothing
- Your OKNothing goes out, so it needs no OK.
Is it for you?
Use it when it fits.
Read both lists. If the left one sounds like you, the Writing Design Docs skill helps.
Use it when
- ✓ Writing a proposal or RFC
- ✓ Scoping a migration plan
- ✓ Handing a spec to a reviewer
Skip it when
- – Recording a decision already taken
- – Writing a runbook or status report
Writing Design Docs skill, answered.
Does it write the design doc?
The skill can, but the loop's job is the check before review.
What about a decision already taken?
That belongs to the recording-decisions skill, not this loop.
What are the five vagueness defects?
Unresolved placeholders, missing acceptance criteria, undefined references, no verifiable output, and an outcome with no direction for how.
How do I install the Writing Design Docs skill?
Copy the prompt at the top into your agent. It installs the skill from riekelt/technical-writer and sets up the habit. Or run npx skills add riekelt/technical-writer --skill writing-design-docs.
Is the Writing Design Docs skill free?
Yes. It is published under MIT. Habit is free too.
Writing Design Docs. Now as a habit.
Install the Writing Design Docs skill and make it a habit: follow https://gethabit.dev/skills/riekelt/writing-design-docs.md
All riekelt skills →More planning skills →
Works in
- Claude Code
- Codex
- Cursor
- ChatGPT
- Claude app
Made by riekelt, published under MIT. Habit links to the original and never changes it. Is this your skill?