design-rationale — Claude Code skill: defend design decisions
Writes a design rationale that ties a decision to user needs, business goals and principles. Useful before a review or a handoff.
npx skills add Owl-Listener/designer-skills --skill design-rationale -a claude-codeWhat design-rationale does
The skill lays out seven sections: decision, context, options considered, evidence, reasoning, trade-offs and a validation plan. The agent walks through them and produces a document that links the choice to research, goals and design principles instead of personal taste.
A quality checklist keeps the output honest. It asks for evidence or principles, requires the rejected alternatives to be named, and checks that the text is specific enough to be useful months later. There is also a list of moments when a rationale is worth writing: a major direction change, a departure from established patterns, a debated choice, or a shift from a previous approach.
The skill advises writing during the decision rather than after it, storing the rationale next to the design files and referencing it in handoff docs. For a live argument with colleagues it is the wrong tool — that is what design-negotiation covers.
What it helps with
- defend a design decision to the team and stakeholders
- record which alternatives were explored and why they lost
- explain a departure from an established pattern
- prepare the rationale section of a handoff document
- reconstruct the context of a decision months later
Example prompts for the agent
- Write a rationale for switching to the new navigation: context, options, evidence, trade-offs
- Draft the rationale for changing the auth pattern and add a validation plan with metrics
- Put together the reasoning behind the contested grid decision so I can attach it to the review
How to install design-rationale
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill design-rationale -a claude-code2Manually: put the files in place
~/.claude/skills/design-rationale/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/design-rationale/
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill design-rationale -a codex2Manually: put the files in place
.agents/skills/design-rationale/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill design-rationale -a cursor2Manually: put the files in place
.cursor/skills/design-rationale/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Owl-Listener/designer-skills design-rationale2Manually: put the files in place
.github/skills/design-rationale/SKILL.md1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill design-rationale -a gemini-cli2Platform CLI
gemini skills install https://github.com/Owl-Listener/designer-skills --path designer-toolkit/skills/design-rationaleManually: put the files in place
.devin/skills/design-rationale/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill design-rationale -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about design-rationale
How do I install design-rationale in Claude?
Run npx skills add Owl-Listener/designer-skills --skill design-rationale -a claude-code. The skill lands in ~/.claude/skills/design-rationale/SKILL.md.
What does design-rationale do?
It writes a design rationale in seven parts: decision, context, options considered, evidence, reasoning, trade-offs and a validation plan.
How is design-rationale different from design-negotiation?
This one produces a written document someone will read later. design-negotiation is for a live conversation where the decision is argued out loud.
Source text
SKILL.md · MIT
--- name: design-rationale description: Write rationale connecting decisions to user needs, business goals, and principles. Use when a decision needs defending in writing. For a live conversation, use `design-negotiation`. --- # Design Rationale You are an expert in articulating the reasoning behind design decisions. ## What You Do You write clear design rationale that connects decisions to evidence, principles, and goals. ## Rationale Structure ### 1. Decision What design decision was made? Be specific about what was chosen. ### 2. Context What problem or need prompted this decision? What constraints exist? ### 3. Options Considered What alternatives were explored? Brief description of each. ### 4. Evidence What informed the decision? User research, data, best practices, competitive analysis, usability testing. ### 5. Reasoning Why this option over the alternatives? Connect to user needs, business goals, design principles, and technical feasibility. ### 6. Trade-offs What are the known compromises? What was deprioritized and why? ### 7. Validation Plan How will you know if this decision was right? What metrics or feedback will confirm? ## When to Write Rationale - Major design direction decisions - Departures from established patterns - Controversial or debated choices - Decisions that will be questioned later - Changes from previous approaches ## Rationale Quality Checklist - Connects to user needs (not just designer preference) - References evidence or principles - Acknowledges alternatives and trade-offs - Is specific enough to be useful months later - Written for the audience who will read it ## Best Practices - Write rationale during the decision, not after - Keep it concise but complete - Store rationale alongside the design files - Reference in handoff documentation - Use rationale in design reviews to explain choices
© Owl-Listener · MIT · Owl-Listener/designer-skills
