superdesigndev__superdesign-skill/INSTALL.md

Superdesign — one-paste setup (for AI coding agents)

The user wants to start designing on the Superdesign canvas. Do EVERY step below in order, automatically. Pause only where login needs the browser. You MUST finish by generating a first design and returning its preview link. Do NOT stop at login.

The flow is simple and sequential: install → log in → init → ask what to design → design. Do NOT propose design ideas, and do NOT run things in parallel — just init, then ask the user what they want.

⛔ Hard gate (real-codebase path): do NOT create a project, create a draft, or run ANY superdesign design command until init has finished (.superdesign/init/ written with all files). This flow assumes a real codebase to init; for an empty/scratch/sandbox workspace there is nothing to init — see the no-codebase branch in skills/superdesign/SKILL.md (Step 1).

Step 1 — Install the Superdesign skill into yourself

Already installed? If you are reading this because the Superdesign skill or plugin is already loaded in this session (you can invoke superdesign / superdesign:superdesign), skip straight to Step 2 — do not install a second copy.

Claude Code — install the plugin instead of the skill, and tell the user to run these two, since /plugin is a user-typed command you cannot run for them:

/plugin marketplace add superdesigndev/superdesign-skill
/plugin install superdesign@superdesign

Then continue at Step 2. Do NOT also run npx skills add — that leaves a second, unnamespaced copy of the same skill.

DeepSeek Harness (dsh) — install the bundle into the profile you boot, then restart dsh:

dsh plugin --profile <your-profile> add github:superdesigndev/superdesign-skill

Then continue at Step 2. Do NOT also run npx skills add — the bundle already publishes this skill. (Without the bundle, dsh also picks the skill up from ~/.agents/skills/superdesign/, which is where npx skills add -g writes it.)

Every other agent — run (non-interactive), substituting your own agent's slug:

npx skills add superdesigndev/superdesign-skill -g -a <your-agent-slug> -y

• -g persistent (global) · -a target agent · -y skip prompts.
• The skills CLI (vercel-labs/skills) supports 70+ coding agents and writes the skill to the correct directory for each. Use the slug for the agent you are. Common slugs: claude-code, cursor, codex, opencode, cline, windsurf, gemini-cli, github-copilot, zed, aider, continue, amp, warp, kilo, goose, crush, droid, junie, trae, qoder, devin, augment, roo. Full list: https://github.com/vercel-labs/skills#supported-agents.

Fallback — if npx skills is unavailable or fails, install manually. Download or clone this repository, then copy the entire skills/superdesign/ directory into a superdesign/ folder inside your agent's skills directory. Preserve the directory structure, including SKILL.md, the references/ directory, and the deprecated compatibility forwarder files at the skill root.

Typical skills dirs: ~/.claude/skills/superdesign/ (Claude Code) · .agents/skills/superdesign/ (Cursor, Codex, Cline, Gemini CLI, GitHub Copilot, Zed, Warp, DeepSeek Harness) · or your agent's documented skills path.

Step 2 — Auth

Ensure the CLI is installed (superdesign --version; if missing, npm install -g @superdesign/cli@latest), then run superdesign login (opens a browser — ask the user to click to authenticate, then wait for success).

Step 3 — Run init (the repo design-system extraction)

Run the Superdesign init analysis — it scans the repo and writes the UI context files to .superdesign/init/ (per references/INIT.md in the installed skill). This is the one-time slow step (~3–5 min the first time). After the first UI design, the skill also writes .superdesign/resume.json so unchanged targets can resume their project, draft, components, and context bundle across later agent sessions.

Then move to Step 4. Do NOT propose designs and do NOT start any design command until init is complete.

Step 4 — Ask the user what they want to design

Ask one short, open question and wait for their answer:

What would you like to design? (a page, a component, a flow — name it, or paste a task/spec)

⛔ Do NOT propose options, do NOT pick a target for them, and do NOT list "high-leverage ideas." Just ask, and use their answer as the design target. (Proposing has produced worse results — let the user say what they want.)

If their answer is ambiguous about WHICH page/screen (e.g. a feature that spans several), ask one quick clarifying question to pin the exact target. Otherwise proceed.

Step 5 — Design

Once init is complete AND you have the user's target, follow the SuperDesign design SOP (see references/SUPERDESIGN.md in the installed skill): first try the warm path in references/RESUME.md for a previously initialized target. A valid warm resume hash-checks and reuses the saved context without rereading init/source files or repeating reproduction. For a cold/new target, read the init files, gather the real source context for the target page (mind the payload budget — line-range 1000+ line files to their render section; never thin-retry on a 400), create the project, produce the pixel-perfect reproduction, persist resume state, then branch variations. Return the preview / canvas URL.

If a generate fails with a 400 (payload), trim the big files to their render sections and retry the SAME faithful call — never retry with thinned context, which makes the model invent a generic page. If it genuinely cannot fit, stop and report the exact error. Never stop silently, and never leave the user without the preview link.