102.7K+Download
Skip to the usage guide
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 OpenDesignView 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

  1. 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).

  2. 02
    Parallel Variant Generation with anti-convergence

    Launches N Agent subagents (one per variant) in a single message for concurrent execution.

  3. 03
    HTTP Comparison Board with Feedback Loop

    Runs $D compare --serve to generate HTML board and start HTTP server on random port.

  4. 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)
  • PNG generation needs the gstack design binary and its configured generation capability. If that binary is unavailable, the source falls back to HTML wireframes rather than promising images.

What to Provide

  • Screen, Audience and TaskDescribe who uses the screen, what they need to accomplish, how they arrive and what follows. Share existing DESIGN.md or product context when available.
  • Existing Page to EvolveProvide the page URL if you want alternatives to a current design. The source uses a screenshot of that named page as the starting point.
  • Edge Cases and Variant CountInclude empty, error and mobile states that matter. The source defaults to three directions and allows up to eight.

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.

  1. All Artifacts to ~/.gstack/projects/$SLUG/designs/

    Final mockups, comparison boards and approval records live under ~/.gstack/projects/$SLUG/designs/. The generation procedure also uses /tmp/ as a temporary staging location before copying PNGs to that final directory.

  2. 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).

  3. 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.

  4. 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.

  5. Confirm Feedback Before Saving

    After receiving feedback (via HTTP POST or AskUserQuestion fallback), output a summary with preferred variant, ratings, comments, and direction.

  6. DESIGN.md Is the Default Constraint

    If DESIGN.md exists, follow the project's design system by default.

  7. 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.

Editorial starter example based on the source workflow; not a recorded run.

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 check your installed version’s skill list and supported tools. If this skill is absent, consult the current import guide and the upstream setup instructions. The source review is not a live compatibility test.

Download OpenDesignRead 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

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

PNG generation uses the gstack design binary, while the source specifies an HTML-wireframe fallback if it is unavailable. The workflow also refers to gstack scripts and local browser tools; importing the instruction file alone does not install all of them. The SKILL.md does not give a complete provider credential checklist, so check the repository setup before generating images.

Comparison and feedback records are stored locally. A local comparison board does not imply that the image-generation step is offline or dependency-free.

Design Shotgun

Run design-shotgun on a Real UI Design Task.

Start with the example task above, supply the listed inputs and check the required tools. Review the output against the checklist before using it in a project.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/garrytan/gstack --skill design-shotgun