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.
Install
npx skills add pproenca/dot-skills --skill write-design-docsgit 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-docsPersonal 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.
Details
- Skill name
write-design-docs- Repository
- pproenca/dot-skills
- 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
228pproenca/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.
37signals Rails
228pproenca/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.
Acceptance Pipeline Catalog
228pproenca/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.
Wxt Browser Extensions
228pproenca/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.
Worldbuilding
191jwynia/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.
AI Content Pipeline
223NeverSight/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
Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.