design-shotgunby Garry Tan

Design Shotgun Skill.

A Claude Code and Codex skill for UI design: generates several design variants in parallel and opens a comparison board for feedback.

Web & UI
UI code

Download OpenDesign View usage guide

garrytan/gstack · design-shotgun/SKILL.mdSKILL.md

--- name: design-shotgun description: Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate. (gstack) --- ## When to invoke this skill ## Confusion Protocol ## Claimed Limitations Need Evidence ## Continuous Checkpoint Mode ## Context Health (soft directive) ## Question Tuning (skip entirely if QUESTION_TUNING: false)

Front matter and section headings read from the upstream file on 2026-09-14 · 52,851 characters in full

01 What it does

What the design-shotgun Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

design-shotgun is a visual design exploration tool that generates multiple AI design variants in parallel, opens them side-by-side in a comparison board served over HTTP, and collects structured feedback. It remembers the user's taste across sessions via a persistent taste profile (fonts, colors, layouts, aesthetics) and biases new generations toward demonstrated preferences.

The skill enforces anti-convergence (every variant must use different fonts, palettes, and layouts) and saves all artifacts to ~/.gstack/projects/$SLUG/designs/ for cross-session persistence. It supports both new explorations and revisiting prior sessions, with feedback loops for regeneration, remixing elements across variants, and iteration until the user approves a direction.

What it produces

N variant PNGs saved to ~/.gstack/projects/$SLUG/designs/<screen-name>-YYYYMMDD/variant-{letter}.png
HTML comparison board served over HTTP at random port with feedback collection UI (design-board.html)
approved.json file recording preferred variant, ratings, comments, and date for cross-session taste learning
Updated taste-profile.json (schema v1) with confidence-weighted approved/rejected patterns per dimension

See the example prompt ↗

How It Works

01
Session Detection and Taste Recovery
Checks ~/.gstack/projects/$SLUG/designs/ for approved.json files from prior sessions and reads the persistent taste-profile.json (schema v1 with confidence decay 5% per week).
02
Parallel Variant Generation with anti-convergence
Launches N Agent subagents (one per variant) in a single message for concurrent execution.
03
HTTP Comparison Board with Feedback Loop
Runs $D compare --serve to generate HTML board and start HTTP server on random port.
04
Feedback Confirmation and Taste Update
Summarizes preferred variant, ratings, and comments; confirms via AskUserQuestion before saving.

02 Find your fit

When to Use the design-shotgun Skill

Use the design-shotgun skill in Claude Code or Codex when the job is UI design of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

Standalone design exploration run anytime during development for any UI feature the user describes but hasn't seen yet
Visual brainstorming when the user says 'I don't like how this looks' and wants to see alternative directions for an existing page
Revisiting prior design explorations to adjust choices or explore new variants for the same screen

Know the Boundaries

Finalizing production-ready HTML/CSS implementation (use /design-html for that after approving a direction)
Single-variant generation without comparison (the skill generates multiple variants in parallel for side-by-side comparison)

What to Provide

Screenshot URL for evolve pathIf user says 'I don't like THIS', ask for the URL.
Variant count (default 3, up to 8)Prompted in context-gathering AskUserQuestion. More variants for important screens.

03 Inside the skill

Rules the design-shotgun Skill Gives Claude Code and Codex

7 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

All Artifacts to ~/.gstack/projects/$SLUG/designs/
Design mockups, comparison boards, and approved.json must be saved to ~/.gstack/projects/$SLUG/designs/, never to .context/, docs/designs/, /tmp/, or project-local directories.
Taste Memory Biases Generation by Default
Reads taste-profile.json (schema v1 with confidence decay 5% per week) and summarizes top-3 approved/rejected entries per dimension (fonts, colors, layouts, aesthetics).
Generate to /tmp/ Then Copy Due to Sandbox Restrictions
Always generate PNGs to /tmp/variant-{letter}.png first, then cp to the final ~/.gstack/projects/$SLUG/designs/ location.
Two Rounds Max on Context Gathering
Pre-fill what you inferred from DESIGN.md, PRODUCT.md, and codebase. Ask for missing context in one AskUserQuestion.
Confirm Feedback Before Saving
After receiving feedback (via HTTP POST or AskUserQuestion fallback), output a summary with preferred variant, ratings, comments, and direction.
DESIGN.md Is the Default Constraint
If DESIGN.md exists, follow the project's design system by default.
Comparison Board Is the Chooser, Not AskUserQuestion
Do not use AskUserQuestion to ask which variant the user prefers. The comparison board UI is the chooser.

04 Put it to work

Install design-shotgun in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add design-shotgun to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/garrytan/gstack --skill design-shotgun

Generic skills CLI form for design-shotgun/SKILL.md; the repository may document its own path.

Give the Skill a First UI Design Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Explore design directions for the [dashboard homepage] where [enterprise SaaS users] land after login. I want to see 4 variants — one minimal/data-dense for power users, one with more guidance for first-timers, one that emphasizes recent activity, and one optimized for mobile-first. The existing dashboard in src/app/dashboard/ feels cluttered and users complain they can't find the export button. Edge cases: zero data state, 50+ recent items, and users who only use mobile.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Read each generated PNG inline so the user sees all variants at once in the terminal before the board opens
Verify comparison board is serving and parse board URL from stderr output (BOARD_URL: http://127.0.0.1:N/boards/<id>/)
Check for feedback files (feedback.json for Submit, feedback-pending.json for Regenerate/Remix) in design directory
Run quality check on each generated variant using $D check --image <path> --brief <brief>; retry generation once if check fails

In OpenDesign import design-shotgun from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Garry Tan
Repository: github.com/garrytan/gstack Branch main
Skill file: design-shotgun/SKILL.md Content checksum recorded at verification; commit 71f6048
License: MIT From LICENSE.
Repository stars: 132,921 GitHub snapshot taken 2026-09-14 for the whole garrytan/gstack repository, which contains 7 skills in this catalog. Not a rating or usage count for design-shotgun.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

When to invoke this skillStandalone design exploration for UI features, visual brainstorm, 'I don't like how this looks'
Preamble (run first)Runs gstack-skill-start, reads STATUS lines, handles degraded mode, instruction blocks, session detection
Plan Mode Safe OperationsAllowed in plan mode: $B, $D, codex exec/review, writes to ~/.gstack/, plan file, open for artifacts
Skill Invocation During Plan ModeSkill instructions are executable, not reference; AskUserQuestion satisfies end-of-turn; ExitPlanMode after workflow completes
AskUserQuestion FormatTool resolution branches on SESSION_KIND/CONDUCTOR_SESSION; prose fallback for unavailable/failed calls; mandatory confirmation triad
Artifacts Sync (skill start)Skill-start output already ran sync; act on GBrain hint, ARTIFACTS_SYNC lines, one-time consent gate
Model-Specific Behavioral Patch (claude)Todo-list discipline, think before heavy actions, prefer dedicated tools over Bash
VoiceGStack voice: concrete, builder-to-builder, lead with point, tie choices to user outcomes, bounded closers
Context RecoveryAt session start/compaction: recover recent artifacts, decisions, checkpoints, timeline; suggest next skill if RECENT_PATTERN implies one
Writing StyleGloss jargon first use, outcome-framing, short sentences; skip if EXPLAIN_LEVEL: terse or user requests terse
Completeness Principle — Boil the OceanAI makes completeness cheap; recommend full coverage; Completeness: X/10 when options differ in coverage
Confusion ProtocolFor high-stakes ambiguity, STOP, name it, present 2-3 options with tradeoffs, ask

The Skill's Own Description

“Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate. (gstack)”

Front-matter description from SKILL.md. The full file is about 52,851 characters. Read the full file on GitHub.

06 Before you install

Questions About the design-shotgun Skill

Answers come from the SKILL.md as read on 2026-09-14, not from a recorded run.

What does the skill need to generate variants (dependencies, API keys, local tools)?

The skill requires the design binary at ~/.claude/skills/gstack/design/dist/design (checked in DESIGN SETUP step). The binary handles image generation and quality checks. If unavailable, the skill falls back to HTML wireframes.

The comparison board runs a local HTTP server on a random port (no external dependencies). Taste memory and approved.json files are stored locally in ~/.gstack/projects/$SLUG/designs/.

Design Shotgun

Run design-shotgun on a Real UI Design Task.

Download OpenDesign, import design-shotgun from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills