Use after explore to design the architecture and technical approach. Takes research findings and creates a concrete technical design. Outputs design.md.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Transform research into architecture. This skill takes the findings from explore and works with the user to create a concrete technical design.
Input: .workflow/NNN-feature-slug/research.md
Output: .workflow/NNN-feature-slug/design.md
Announce at start: "I'm using the design skill to work out the architecture for this feature."
explore skill completes/designplan skill (design informs implementation steps)Never ask multiple questions in one message.
Bad:
"What database should we use? Also, do you prefer REST or GraphQL? And should we add caching?"
Good:
"For the data layer, I'm thinking PostgreSQL based on your existing setup. Does that work, or do you have a different preference?"
[Wait for answer, then ask next question]
Goal: Ground the design in research.
.workflow/NNN-feature-slug/research.md"Based on the research, here's what we're working with:
**Building:** [Feature name]
**Key constraint:** [Most important limitation]
**Existing patterns:** [What we should follow]
I have a few design decisions to work through with you. Let's start with [first decision]."
Goal: Make key technical choices collaboratively.
For each decision point:
Format:
"For [component/aspect], I see a few approaches:
**Option A: [Name]** (Recommended)
- Pro: [benefit]
- Con: [drawback]
- Fits because: [why it matches their context]
**Option B: [Name]**
- Pro: [benefit]
- Con: [drawback]
**Option C: [Name]**
- Pro: [benefit]
- Con: [drawback]
I'd go with Option A because [reasoning]. Does that work for you?"
Common decision areas:
Goal: Define what we're building in concrete terms.
For each major component:
Format:
"Let me walk through the [component] design:
**[Component Name]**
Purpose: [What it does]
Structure:
- [Element 1]: [responsibility]
- [Element 2]: [responsibility]
Interactions:
- Receives: [input from where]
- Produces: [output to where]
Does this structure make sense so far?"
[Wait for confirmation before next component]
Goal: Capture decisions in design.md.
Write .workflow/NNN-feature-slug/design.md:
# Design: [Feature Name]
**Date:** YYYY-MM-DD
**Status:** Design complete, ready for planning
**Research:** [Link to research.md]
## Overview
[2-3 sentences: what we're building and the approach]
## Architecture
### High-Level Structure
[ASCII diagram or description of how components fit together]
### Components
#### [Component 1]
**Purpose:** [What it does]
**Interface:**
[API/interface definition - pseudocode or actual syntax]
**Responsibilities:**
- [Responsibility 1]
- [Responsibility 2]
**Dependencies:**
- [What it needs]
#### [Component 2]
[Same structure]
## Data Model
[If applicable]
[Schema or data structure definition]
## Key Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| [Decision 1] | [What we chose] | [Why] |
| [Decision 2] | [What we chose] | [Why] |
## Error Handling
[How errors flow through the system]
## Testing Strategy
- **Unit tests:** [What we'll unit test]
- **Integration tests:** [What we'll integration test]
- **Edge cases:** [Key edge cases to cover]
## Open Items
- [ ] [Anything still to be decided during planning/implementation]
## Non-Goals
[What we're explicitly NOT doing in this iteration]
After writing design.md:
"I've completed the design and saved it to
.workflow/NNN-feature-slug/design.md.Architecture summary: [1-2 sentences] Key decisions: [Bullet the main choices made]
Ready to create the implementation plan? I'll use the plan skill to break this into concrete steps."
Transition to: plan skill (if user confirms)
Never:
Always:
.workflow/NNN-slug/