GPT Image Design Workflows

A reusable agent skill for using OpenAI GPT Image models in design and software-building workflows.

It helps coding agents turn a user objective into low-cost visual exploration, tracked iteration, and polished final image assets before moving into frontend implementation, direct publishing, or optional structured design tools.

What It Does

• Supports OpenAI and Replicate providers for running gpt-image-2
• Generates design references and production image assets with custom aspect ratios/resolutions
• Edits existing images and multi-image references
• Supports Responses API image iteration with previous_response_id and image_generation_call_id (OpenAI only)
• Resolves and downloads multiple generated images in parallel (leverages Promise.all to minimize download latency)
• Saves outputs into a topic-organized image memory palace
• Writes metadata manifests with prompts, model, size, quality, latency, request IDs, and estimated cost
• Provides prompting patterns for UI mockups, ads, product mockups, diagrams, and edits
• Encourages cheap first-pass exploration before upgrading only the strongest directions to higher quality

Who It Is For

Use this skill when you want an agent to:

• create visual references before building UI
• generate launch graphics, model cards, social visuals, or product mockups
• make several image variations and keep the prompt history organized
• edit an image while preserving layout, brand, identity, or structure
• keep a reusable local archive of generated images and manifests
• hand off a visual direction into frontend code or an optional structured design tool

Installation

Install With The Skills CLI

Install with the skills CLI:

npx skills add Ashish-Soni08/gpt-image-design-workflows

Restart your agent after installing so the skill metadata is rediscovered.

Install For Codex

Clone or copy this repository into your Codex skills directory:

~/.codex/skills/gpt-image-design-workflows

Windows example:

git clone https://github.com/Ashish-Soni08/gpt-image-design-workflows.git `
  C:/Users/<you>/.codex/skills/gpt-image-design-workflows

Restart Codex after installing.

Install For Claude Code

Install with the skills CLI:

npx skills add Ashish-Soni08/gpt-image-design-workflows

Or clone/copy into:

~/.agents/skills/gpt-image-design-workflows

Restart Claude Code after installing.

Requirements

• Node.js 22 or newer recommended
• An API Key/Token for either OpenAI or Replicate

Setup

Set your API keys in the environment. Do not hard-code them in files.

OpenAI Setup

PowerShell, current session:

$env:OPENAI_API_KEY="your_api_key_here"

macOS/Linux:

export OPENAI_API_KEY="your_api_key_here"

Replicate Setup

PowerShell, current session:

$env:REPLICATE_API_TOKEN="your_token_here"

macOS/Linux:

export REPLICATE_API_TOKEN="your_token_here"

Tip

The script automatically detects which provider to use! If REPLICATE_API_TOKEN is found in the environment and OPENAI_API_KEY is not, the script runs predictions via Replicate. You can also explicitly choose the provider with the --provider flag.

Image Memory Palace

By default, images are saved under:

./image-memory-palace

Override this with your preferred long-term archive. For example:

--memory-root D:/Github/design/image-memory-palace

or:

$env:IMAGE_MEMORY_PALACE_ROOT="D:/Github/design/image-memory-palace"

Each topic receives a folder and manifest:

image-memory-palace/
  ai-builder-dashboard/
    20260501-114544_builder-blueprint_generate_low_1536x1024_v01-of-02.png
    manifest.json
  _index/
    global-manifest.json

Output filenames use:

YYYYMMDD-HHMMSS_label_mode_quality_size_v01-of-02.png

Use --label to name a run or creative direction. If --label is omitted, the script falls back to the topic slug.

How Agents Should Use It

The core loop is:

objective -> brief -> low-cost variants -> evaluate -> selective refinement -> final asset or handoff

Use a budgeted approval model for smooth autonomy:

1. If the user gives a broad objective, create a concise brief and propose a small exploration budget.
2. Before the first paid API call, summarize model, mode, size, quality, variant count, memory topic, and estimated cost when available.
3. Ask for approval unless the user already gave a specific generation/edit command.
4. After approval, continue without asking again while staying inside the approved budget.
5. Pause before exceeding budget, increasing variant count, using quality high, using experimental sizes above 2560x1440, editing sensitive/private images, publishing assets, or making uncertain-cost API calls.

The routing rule is:

Need a shareable visual artifact? Use GPT Image directly.
Need implementation-ready UI? Use GPT Image -> optional design-tool handoff -> code.

For direct artifacts, generate 2-8 candidates, pick a winner, then refine with edits or Responses API iteration.

For app screens, generate concepts first, then rebuild the best direction structurally in code or in whatever design tool is available.

Quality defaults:

• low: fast exploration, batch variants, cheap previews.
• medium: default for strong design references and marketing concepts.
• high: dense text, diagrams, charts, final assets, high-resolution outputs, or identity-sensitive edits.

For gpt-image-2, size must use WIDTHxHEIGHT, both edges must be multiples of 16, max edge must be under 3840, aspect ratio must be at most 3:1, and total pixels must be between 655,360 and 8,294,400. Treat sizes above 2560x1440 as experimental.

Generate A Design Reference

Generate with OpenAI (default):

node scripts/gpt_image_workflow.mjs `
  --provider openai `
  --mode generate `
  --topic ai-builder-dashboard `
  --label builder-blueprint `
  --prompt "Create a realistic production UI reference for an AI builder dashboard. Dense but elegant, practical controls, clear hierarchy, realistic app content, no marketing hero." `
  --size 1536x1024 `
  --quality medium `
  --n 3

Generate with Replicate:

node scripts/gpt_image_workflow.mjs `
  --provider replicate `
  --mode generate `
  --topic ai-builder-dashboard `
  --prompt "Create a realistic production UI reference for an AI builder dashboard." `
  --size 1536x1024 `
  --quality medium

Edit Existing Images

node scripts/gpt_image_workflow.mjs `
  --mode edit `
  --topic ai-builder-dashboard `
  --label premium-density-edit `
  --image D:/path/to/reference.png `
  --prompt "Preserve the layout and navigation. Make the visual design more premium, calmer, and more information dense." `
  --size 1536x1024 `
  --quality medium

Responses API Iteration

Use this when you want to keep refining the same generated image.

node scripts/gpt_image_workflow.mjs `
  --mode responses-generate `
  --topic ai-builder-dashboard `
  --prompt "Generate a polished dashboard reference for an AI app builder." `
  --response-model gpt-5.5 `
  --quality medium

Then use the saved response_id or image_generation_call_id from the manifest:

node scripts/gpt_image_workflow.mjs `
  --mode responses-edit `
  --topic ai-builder-dashboard `
  --prompt "Preserve layout. Make the interface denser and more premium." `
  --previous-response-id resp_... `
  --quality medium

Dry Run And Local Validation

Use dry-run mode to verify manifests and folder creation without calling the API:

node scripts/gpt_image_workflow.mjs `
  --dry-run `
  --mode generate `
  --topic skill-test `
  --label dry-run-smoke `
  --prompt "Create a polished UI reference." `
  --size 1024x1024 `
  --quality low

You can also syntax-check the runtime script locally:

node --check scripts/gpt_image_workflow.mjs

Multiple Variations

Use --n to generate multiple candidates in one request:

node scripts/gpt_image_workflow.mjs `
  --mode generate `
  --topic model-card-launch `
  --label editorial-model-card `
  --prompt "Create a premium editorial model card for a new AI model release." `
  --size 1536x1024 `
  --quality medium `
  --n 4

The script records every image in the topic manifest and the global index.

Optional Design-Tool Handoff

This skill does not require Paper MCP, Pencil MCP, or any design MCP server. Generated images can be used directly as implementation references or production assets.

If a compatible design tool is available, use generated images as references, not final UI. A good optional workflow is:

brief -> GPT Image reference -> optional structured design tool -> app implementation -> browser QA

Examples of optional design-tool handoffs:

• Paper MCP (https://paper.design/docs/mcp): rebuild the reference structurally in Paper, inspect selected frames, use screenshots/JSX/styles, and support design-to-code handoff. Local images can be referenced as paper-asset://D:/Github/design/image-memory-palace/<topic>/<image>.png.
• Pencil (https://www.pencil.dev/): use the reference as visual direction for canvas-to-code workflows, webpages, components, layouts, .pen design files, and design/code iteration.
• No design MCP: implement directly in the app from the saved image and manifest.

Security Notes

• Set OPENAI_API_KEY or REPLICATE_API_TOKEN (or REPLICATE_API_KEY) in your environment before making real API calls.
• Do not store API keys or tokens in the repository, skill files, manifests, examples, or prompts.
• Never commit generated private/customer images unless you intend to publish them.

Model Notes

• For gpt-image-2, omit input_fidelity; the model already processes image inputs at high fidelity.
• gpt-image-2 does not support transparent backgrounds.
• Cost is reported as an estimate unless API usage data is available.
• Start with quality low for exploration, then upgrade only selected winners to medium or high.