design-doc
Write a short design document for unclear or important architecture decisions before implementation. Use when a decision is expensive to reverse or crosses team boundaries.
- Installs
- 242
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/owainlewis/blueprint --skill design-doc- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads design-doc automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Design Doc
- Read the brief and any linked docs, code, or plans. Ask one question at a time, with a recommended answer, only when a missing fact would change the design.
- Write
docs/<design-slug>/design.md, 1-3 pages, using the template below. Omit sections that do not apply. - Stop after writing. Do not continue into spec, plan, or implementation until the human confirms.
Rules
- Make the design choice and its tradeoffs easy to review.
- Focus on decisions code will not explain later.
- Do not copy full schemas, APIs, or code unless the exact shape is central.
- Leave Status as Draft and Decision empty. Both are filled during review.
Template
# <Title>
**Status:** Draft | In review | Approved
**Author:** <name> **Date:** <date>
## Summary
One paragraph: the problem, the proposed solution, and why.
## Goals
What this design must achieve.
## Non-goals
What it deliberately does not solve.
## Constraints
Technical, product, migration, compatibility, operational, cost, or time limits.
## Proposed design
How it works. Structure, data flow, key interfaces. Diagram only if it clarifies.
## Alternatives and tradeoffs
Each option considered, why it lost. This is the section reviewers judge.
## Risks
What could go wrong and how it is mitigated.
## Rollout
How it ships: migration, flags, backout.
## Open questions
Decisions still needed and from whom.
## Decision
Filled in after review: what was decided, by whom, when.
FAQ
What does the design-doc skill do?
Write a short design document for unclear or important architecture decisions before implementation. Use when a decision is expensive to reverse or crosses team boundaries.
How do I install design-doc?
Run npx skills add https://github.com/owainlewis/blueprint --skill design-doc in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-doc/ (personal) or .claude/skills/design-doc/ (project).
Which AI agents can use design-doc?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is design-doc safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains design-doc?
It is published by owainlewis in owainlewis/blueprint. It has 242 recorded installs.
More from owainlewis/blueprint
review
owainlewis/blueprint
Uses a fresh agent to review an implementation change without editing it. Checks behavior, security, regressions, complexity, tests, docs, and missing proof. Use for code, PR, diff, security, second-opinion, or pre-merge reviews.
plan
owainlewis/blueprint
Turns a reviewed spec or decided brief into ordered tasks for separate agent runs. Use for implementation tasks, tracker tickets, or useful milestones. Do not use for one coding task or its short execution outline.
task-to-pr
owainlewis/blueprint
Open the skill to read its SKILL.md instructions.
spec
owainlewis/blueprint
Open the skill to read its SKILL.md instructions.
refactor
owainlewis/blueprint
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.