Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add prathamdby/skills --skill upfront-design -a claude-code
Open on GitHub

What 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-service design

How to install upfront-design

1Skills CLI (Vercel)

npx skills add prathamdby/skills --skill upfront-design -a claude-code

2Manually: put the files in place

~/.claude/skills/upfront-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/upfront-design/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set19

The whole set →
gh The gh skill lets an agent inspect PRs, discussions, and CI, post replies, and handle GitHub commands that need more than a simple call. CX Codex +1 420installs cursor-agent A skill for Claude Code, Codex, and Cursor runs the local cursor-agent CLI and checks its outcome. It handles tasks involving CLI modes, sessions, and worktrees. CX Codex +1 347installs codex Runs the local Codex CLI when the agent asks. Triggers when a task requires calling Codex CLI with specific flags and no manual approvals. CX Codex +1 331installs claude-code This Claude Code skill runs the local CLI with selected options and checks the result. It also handles requests to change installation, sign-in, or connected tools. CX Codex +1 329installs todoist-task Creates Todoist tasks directly from your editor. Recognises task requests, resolves project and date details, shows a preview before creating, and verifies the result in Todoist. CX Codex +1 315installs use-skill use-skill pulls a skill from a GitHub link, checks its structure and runs the steps in a temp folder. Nothing lands in your project. CX Codex +1 294installs autoplan The autoplan Claude Code skill drafts implementation plans without asking follow-up questions. It inspects the repository and maps risks to concrete plan steps. CX Codex +1 287installs restate restate — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that retells the agent's last reply in plain words. Kicks in when you need a catch-up or want to know exactly what decision is waiting on you. CX Codex +1 256installs

Project sponsors

Companies that keep this analytics open