upfront-design — skill for Claude Code and Cursor: design before code
upfront-design — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode that runs structured design sessions before any code is written. It pauses after each of five phases until the user approves the output.
MIT 321 installs ★ 6 updated 2026-11-10
npx skills add prathamdby/skills --skill upfront-design -a claude-codeWhat upfront-design does
The skill runs across six platforms: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. On each invocation it routes the request: new design, resume a draft, or check an open milestone on an approved design. Small requests — one module, no contract or public-signature changes, one-sentence outcome — get a DIRECT response with no file or ledger. Everything else goes through five phases.
The phases are Product, System, Program, Slices, and Finalize. Each one ends with AWAITING_USER and writes approved content before the next begins. Design files are stored outside repositories at <anchor>/designs/<basename>-<slug>-<YYYY-MM-DD-HHmmss>.md; the ledger is written via atomic rename through a sibling temporary file. ADR trees at docs/adr/, adr/, doc/adr/, and docs/decisions/ are picked up silently if they exist.
The Check route runs against an approved design: the skill shows exact commands for the first open, non-deferred milestone and waits for approval before executing them. A box is ticked only with outcome proof that matches the design's symbols — a clean exit code alone is not enough. references/design.md must exist before the first run; without it the phases have no template to fill.
What it helps with
- agree on a system shape before writing any code
- resume an interrupted design from the first unfilled section
- verify an open milestone against an approved design
- record ADRs for hard-to-reverse architectural decisions
- split a feature into vertical PRs with explicit boundary contracts
Example prompts for the agent
- Run upfront-design for a new authentication service
- Resume the draft design for
payment-flow - Check the next open milestone for the
auth-servicedesign
How to install upfront-design
1Skills CLI (Vercel)
npx skills add prathamdby/skills --skill upfront-design -a claude-code2Manually: put the files in place
~/.claude/skills/upfront-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/upfront-design/
1Skills CLI (Vercel)
npx skills add prathamdby/skills --skill upfront-design -a codex2Manually: put the files in place
.agents/skills/upfront-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add prathamdby/skills --skill upfront-design -a cursor2Manually: put the files in place
.cursor/skills/upfront-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install prathamdby/skills skills/engineering/upfront-design2Manually: put the files in place
.github/skills/upfront-design/SKILL.md1Skills CLI (Vercel)
npx skills add prathamdby/skills --skill upfront-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/prathamdby/skills --path skills/engineering/upfront-designManually: put the files in place
.devin/skills/upfront-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add prathamdby/skills --skill upfront-design -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 upfront-design
How do I install upfront-design in Claude Code?
Run npx skills add prathamdby/skills --skill upfront-design -a claude-code. The skill will be available at ~/.claude/skills/upfront-design/SKILL.md.
What does the upfront-design skill do?
It guides a design through five phases — Product, System, Program, Slices, Finalize — pausing after each to save approved content before moving on. Small, self-contained tasks get a direct answer with no file created.
Is references/design.md required for the skill to work?
Yes. The skill uses references/design.md as the document template when creating a new design. Without it the phases have nothing to populate.
Source text
SKILL.md · MIT
--- name: upfront-design description: > When the user wants a design agreed before coding, a draft resumed, or an approved milestone checked. --- # Upfront design ## Route and persistence A design has request/status frontmatter and a `# Design:` title. New request → design; draft → first missing section; approved → check next open milestone; another status → `BLOCKED`. A named revision phase removes later sections only after the user authorizes that revision. Resolve this skill's absolute anchor. Store new designs at `<anchor>/designs/<basename>-<slug>-<YYYY-MM-DD-HHmmss>.md`, outside repos. `<basename>` is the first repo's root directory name. After a path exists, persist approved phases and the ledger through sibling temporary files and atomic rename before advancing. Record `request | size | design | phase | approvals | ADR offers | terminal`. Keep the ledger at `<design>.ledger` on `AWAITING_USER`; remove on other terminals. Small means one module, no contract/data/public-signature change, and a one-sentence outcome. Return `DIRECT` plus that sentence without a file/ledger. Otherwise find ADR trees (`docs/adr/`, `adr/`, `doc/adr/`, `docs/decisions/`); absence is silent. Create the document using `references/design.md`. Done when route, size, path/frontmatter, and relevant ADRs are fixed. ## Design phases Each phase pauses with `AWAITING_USER`; write its approved content before the next starts. Resume at the first missing or explicitly revised phase. 1. **Product:** concrete pain, measurable Success, bold one-line solution, supplied mockup or draft text wireframe/state table for user-facing work, delivery paragraph. Ask the entire question frontier in one numbered round, recommending an answer per question. Done when approved content is persisted. 2. **System:** bold shape + cited pattern, NEW/CHANGED layer roles, sources and constraints with cost reasons, phase-banded sequence. Name ADR conflicts, not overrides. Done when approved content is persisted. 3. **Program:** changed boundary contracts, constraints, real signatures, usage, and roles, not bodies. Cite patterns or assumptions; compare two uncertain layouts, choose one, and record why the other lost. For multiple boundaries, changed dispatch, or unclear async order, apply Wiring views in `references/design.md`. Done when each Success maps to symbols/results and approval is persisted. 4. **Slices:** after prefactoring, start with a thin end-to-end contract/check. One reviewable vertical PR per milestone; name symbols, expected success and relevant failures, assertions/manual proof, repo order, and one open checkbox. Only the user defers/skips; wide refactors expand then contract. Done when every symbol is assigned and approved milestones are persisted. 5. **Finalize:** set approved. Offer ADRs only for decisions hard to reverse, surprising without context, and chosen over a real alternative. On approval use `references/decisions.md`. Done with `DESIGNED` when all five document sections exist and each ADR offer is written or declined. Report design/ADR paths, peer-review, and milestone check route. ## Check For an approved design, follow `references/check.md` for the first open, non-deferred/non-skipped milestone. Show exact commands and obtain approval before running them. Tick only with outcome proof and matching symbols, not a successful exit. Open manual boxes or ambiguous legacy outcomes pause. Never edit product files to make a check pass. Done with `CHECKED` if ticked or all complete, otherwise `AWAITING_USER`. Terminals: `DIRECT` (router no-op success), `AWAITING_USER`, `DESIGNED`, `CHECKED`, `BLOCKED`. Revise via draft status and a named phase.
© prathamdby · MIT · prathamdby/skills