Write Design Docs

Write, revise, or review software design documents using Malte Ubl's "Design Docs at Google" guidance. Use when Codex needs to draft a design doc, technical design, RFC, engineering review doc, architecture proposal, mini design doc, or design-doc review focused on context, goals, non-goals, trade-offs, alternatives, cross-cutting concerns, review lifecycle, and deciding whether a design doc is warranted.

228 stars 19 forksWriting & Content

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add pproenca/dot-skills --skill write-design-docs
Manual install
git clone --depth 1 https://github.com/pproenca/dot-skills.git /tmp/dot-skills
mkdir -p ~/.claude/skills
cp -r /tmp/dot-skills/skills/.experimental/write-design-docs ~/.claude/skills/write-design-docs

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Write Design Docs

## Core Workflow

Use the design doc as a problem-solving and consensus-building tool, not as an implementation manual.

1. Decide whether a design doc is warranted.
   - Write one when the software design is ambiguous, complex, contentious, cross-functional, likely to benefit from senior review, or valuable as organizational memory.
   - Prefer a short note, issue, or direct implementation when the solution is obvious and there are no meaningful trade-offs.
   - Prefer a mini design doc for small but non-obvious changes.

2. Gather the minimum context needed to make the design concrete.
   - Identify the problem, existing landscape, constraints, stakeholders, and decision deadline.
   - Ask focused questions only when missing information would materially change goals, non-goals, or trade-offs.
   - State assumptions explicitly when proceeding with incomplete information.

3. Draft around decisions and trade-offs.
   - Start with objective context and scope.
   - Define goals and non-goals as explicit boundaries.
   - Present the selected design from overview to detail.
   - Explain why the selected design best satisfies the goals under the known constraints.
   - Compare realistic alternatives, including why they were not selected.
   - Cover cross-cutting concerns such as security, privacy, reliability, observability, migrations, and operations when relevant.

4. Keep the document readable.
Read the full skill on GitHub

Details

Skill name
write-design-docs
Path
skills/.experimental/write-design-docs/SKILL.md
License
MIT
Repo updated
15 August 2026

FAQ

What does the Write Design Docs skill do?

Write, revise, or review software design documents using Malte Ubl's "Design Docs at Google" guidance. Use when Codex needs to draft a design doc, technical design, RFC, engineering review doc, architecture proposal, mini design doc, or design-doc review focused on context, goals, non-goals, trade-offs, alternatives, cross-cutting concerns, review lifecycle, and deciding whether a design doc is warranted.

How do I install the Write Design Docs skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add pproenca/dot-skills --skill write-design-docs. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Write Design Docs popular?

It lives in pproenca/dot-skills, which has 228 GitHub stars and 19 forks.

Related skills

12 Factor App

228

pproenca/dot-skills

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

Software Development19

37signals Rails

228

pproenca/dot-skills

37signals Rails coding principles and conventions from DHH, Jorge Manrubia, and the Fizzy/Basecamp/HEY codebase. This skill should be used when writing, reviewing, or refactoring Ruby on Rails code following the 37signals philosophy — vanilla Rails, CRUD controllers, rich domain models, concerns, no service objects, Hotwire, Turbo, Stimulus, Solid Queue, Solid Cache, Solid Cable, multi-tenancy, Minitest, custom auth, or DHH conventions.

Software Development19

Acceptance Pipeline Catalog

228

pproenca/dot-skills

Use when implementing, reviewing, or debugging a Gherkin acceptance-test pipeline with mutation testing. Covers parser, JSON IR, generator, runtime, step handlers, test runner, mutator, value mutation rules, execution, result classification, reporting, project layout, conformance, and agent setup. Based on Uncle Bob's Acceptance Pipeline Specification. Trigger even when the user mentions Gherkin parsing, acceptance test generation, mutation testing for acceptance tests, or building a portable test pipeline.

Testing & QA19

Wxt Browser Extensions

228

pproenca/dot-skills

WXT browser extension performance optimization guidelines. This skill should be used when writing, reviewing, or refactoring WXT browser extension code to ensure optimal performance patterns. Triggers on tasks involving WXT, browser extensions, content scripts, service workers, messaging, and extension APIs.

Writing & Content19

Worldbuilding

191

jwynia/agent-skills

Diagnose world-level story problems. This skill should be used when settings feel thin, institutions feel designed rather than evolved, economies don't make sense, or non-human species feel like humans in costume. Keywords: worldbuilding, setting, world, institutions, economy, culture, species, consequences.

Writing & Content24

AI Content Pipeline

223

NeverSight/learn-skills.dev

Build multi-step AI content creation pipelines combining image, video, audio, and text. Workflow examples: generate image -> animate -> add voiceover -> merge with music. Tools: FLUX, Veo, Kokoro TTS, OmniHuman, media merger, upscaling. Use for: YouTube videos, social media content, marketing materials, automated content. Triggers: content pipeline, ai workflow, content creation, multi-step ai, content automation, ai video workflow, generate and edit, ai content factory, automated content creation, ai production pipeline, media pipeline, content at scale

Writing & Content42

Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.