writing-design-docs skill (riekelt) for Claude Code: write proposals and RFCs that can be argued with

Makes Claude write proposals, RFCs and specs with the conclusion first, a decision box for each choice and the costs spelled out.

Installs: 20.6K; on skills.sh
Stars: 36; on GitHub
Updated: Sep 2026; last repo commit

writing-design-docs gives Claude a skeleton for proposals: a header table, a summary that states the conclusion, analysis split per question, open questions, benefits and costs, and residual risks. Each non-trivial choice gets a Why & What box with the choice, the reasoning, alternatives with their strongest argument and a fallback. Before handing a spec over, Claude checks five vagueness defects. It triggers on proposals, RFCs, migration plans and requests like write up the approach, and it lists technical-writing as required background.

Good for

Engineers who must argue for a change in writing
Tech leads who want trade-offs and rejected alternatives on the page
Anyone turning a rough approach into a spec a reviewer can test

Install writing-design-docs

Claude Code

Copy this prompt.

Install the writing-design-docs skill in Claude Code. Run this command:

/plugin marketplace add riekelt/technical-writer
/plugin install technical-writer@technical-writer

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The skills CLI route must include technical-writing, which writing-design-docs lists as REQUIRED BACKGROUND in its SKILL.md.

From the project README. Source.

What's in the skill

When it loads

Use when writing a proposal, RFC, design document, spec, or migration plan - anything that argues for a change, records a design, or asks readers for input on one. Encodes the proposal skeleton, the Why & What decision box, and the completeness checks. Use whenever a change needs arguing or scoping in writing, even if the user just says "write up the approach".

Sections in SKILL.md

Overview
When to invoke, and not
Skeleton
1. Summary
2. [Context / what was analyzed]
3. [The analysis, split per question]
n. Open questions
n+1. Benefits and costs
n+2. Residual risks and what not to do
Structure rules
The Why & What box
Tone
Completeness check

Key facts

Author: riekelt (owner of the GitHub repo)
License: MIT (LICENSE file and plugin manifest)
Installs on skills.sh: 20,627 as of 2026-11-02
GitHub stars: 36 for the whole riekelt/technical-writer repo, 2026-11-02
What is inside: 1 file: SKILL.md
Needs: The technical-writing skill (SKILL.md lists it as REQUIRED BACKGROUND)
Part of: The technical-writer plugin: 11 skills, 2 agents and 2 commands
Last repo commit: 2026-09-13
Works in: Claude Code per the README install section. The repo also ships Codex and Cursor plugin manifests.

What it includes

Header table, summary, analysis, open questions, benefits and costs
A fixed outline: title and one-sentence subtitle, a table with status, owner, scope, related and audience, then numbered chapters starting with a summary that states the conclusion.
Write · Skeleton
Numbered chapters, goals and non-goals, a grounding section
Includes definitions before behaviour, lettered appendices, input-wanted markers for unfinished parts, owners for open questions, and a split once a document passes roughly 800 lines.
Write · Structure rules
One box per non-trivial choice
Each box states the choice in one sentence, the reasoning including what the choice does not solve, the alternatives considered with their strongest argument, and a fallback.
Try: “Write a design doc for moving our job queue to Postgres, with a Why & What box for the main choice.”
Write · Why & What box
Proposal voice, no superlatives, costs stated
The document stays a proposal, names what it costs, and may say up front that the expected outcome is negative.
Write · Tone
Five vagueness defects checked before handing over
Unresolved placeholders, missing acceptance criteria, undefined references, no verifiable output, and what without how. Execution plans also get a goal, exact files, tests and a verify command per task.
Read · Completeness check

From the official docs

Permissions

Low risk

Claude writes documents into your repository, so check the diff before sharing a draft.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It edits documents in your repo
Claude drafts specs and plans as files. Review the diff before you commit or share them. github.com
The plugin route adds 2 agents and 2 commands
The plugin ships agents prose-reviewer and doc-grounder (both with Read, Glob, Grep and Bash tools) and the commands /prose-review and /ground-docs. The plugin folder has no hooks or MCP config. Use the skills command in the install box if you want only this skill. github.com

Technical details

Turning on read-only	No read-only mode. The skill tells Claude to write or edit documents.
Sign-in and keys	SKILL.md names no account or API key.
Data retention	SKILL.md names no logging or telemetry.
Scopes	Claude drafts and edits proposal documents in your repo

Questions

What does writing-design-docs do?

It makes Claude write a proposal, RFC, design doc, spec or migration plan in a fixed shape: conclusion first, a Why & What box per choice, benefits and costs together.

How do I install writing-design-docs?

Use the install box at the top of this page. The plugin route installs the whole set. The skills command route names technical-writing as well, because this skill lists it as required background.

When should I use recording-decisions instead?

Use recording-decisions for a decision that is already taken. The recording-decisions SKILL.md says not to invoke it for a decision still being argued, which is writing-design-docs, and that the Why & What box becomes the ADR once accepted. The writing-design-docs SKILL.md also says not to invoke it for recording an already-taken decision.

writing-design-docs vs writing-runbooks?

A design doc argues for a change. A runbook is a procedure someone executes. SKILL.md says not to use this skill for procedures or for status reports.

What if my facts have no sources?

SKILL.md says to mark them with a source-wanted marker and keep writing. Claude should never invent a citation and never silently drop the fact.

Is writing-design-docs safe to install?

The skill folder holds only SKILL.md, so it bundles no scripts. It makes Claude draft and edit proposal documents in your repo, so review the diff before you commit or share them. The plugin route adds 2 agents and 2 commands; see the safety section.

Can I use writing-design-docs in the Claude app or Cursor?

The README documents Claude Code, and the repo also ships Codex and Cursor plugin manifests. It does not mention the Claude app. Our advice: this page offers no Claude app upload because the skill works on documents inside a repository, so use Claude Code or Codex.

Information

updated Nov 2, 2026

Repository: riekelt/technical-writer
Folder: plugins/technical-writer/skills/writing-design-docs

riekelt/technical-writer skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

README · github.com
marketplace.json · github.com
writing-design-docs on skills.sh · skills.sh
SKILL.md · github.com
LICENSE · github.com
recording-decisions SKILL.md · github.com
writing-runbooks SKILL.md · github.com