design-bridge

name	design-bridge
description	Use this skill to interview the user for design direction, turn the answers into a detailed design-generation prompt, and generate compact design mockups with OpenAI gpt-image-2. Applies to UI mockups, product design concepts, landing pages, visual systems, posters, and design drafts that should be rendered as images.

GPT Image Design

This skill helps the agent act as a design partner first, then an image-generation operator. Use it when the user wants a design draft, UI mockup, product concept, or a prompt for gpt-image-2.

Required Workflow

1. Before writing the final image prompt, ask the user for missing design details. Ask only the questions that matter, usually 3-6 at once.
2. Turn the answers into a concise design brief. If the user gives conflicting preferences, state the assumption you will use.
3. Write a final gpt-image-2 prompt that is specific enough for image generation.
4. Before calling the API, show the final prompt and ask for confirmation unless the user has already explicitly said to generate immediately. Mention that image generation can consume the user's OpenAI account balance.
5. Generate one image by default. Keep output size modest unless the user asks for more resolution.
6. Put generated files under the current project directory, normally generated-designs/.
7. After generation succeeds, try to open the generated image with open <image-path>. If open fails or is unavailable, report the image path instead.

Questions To Ask

Ask about the missing items below before writing the final prompt:

• Deliverable: app screen, landing page, dashboard, poster, brand concept, icon, etc.
• Platform and aspect ratio: mobile, desktop, tablet, square, slide, social post.
• Audience and goal: who uses it, what action or feeling the design should support.
• Required content: exact text, product name, UI labels, logo/asset references, language.
• Visual direction: style references, mood, color preferences, density, typography feel.
• Layout requirements: sections, hierarchy, navigation, cards, data tables, forms, imagery.
• Constraints: things to avoid, accessibility needs, brand rules, realism vs stylization.

If enough information is already present, do not re-ask it. Ask only for the gaps that affect the design.

Prompt Shape

Write the final image prompt as a design brief, not as a vague art prompt. Include:

• Artifact type and canvas: exact format, aspect ratio, and target device.
• Product context: what the design is for and what the user should understand first.
• Composition: layout structure, major regions, spacing, hierarchy, focal point.
• Visual system: color palette, typography style, iconography, shadows, borders, materials.
• Content: exact visible text in quotes; specify when text must be legible.
• Interaction state: selected tabs, empty/loading/error state, data examples, cursor state if relevant.
• Image constraints: no watermarks, no extra text, no distorted UI, no unreadable microcopy.

Prefer concrete nouns and measurable layout language. Avoid generic phrases like "modern and clean" unless paired with specific visual decisions.

Generation Defaults

Use the OpenAI Image API with:

• model: gpt-image-2
• n: 1
• size: 1024x1024 by default
• Mobile mockups: 1024x1536
• Desktop or slide mockups: 1536x864 or 1536x1024
• quality: medium by default; use high only for dense UI text or detailed visual systems.
• output_format: webp by default to keep files smaller.
• output_compression: 85 for webp or jpeg.
• background: omit by default, or use auto / opaque. Do not request transparent backgrounds with gpt-image-2.

Avoid dimensions above roughly 2K on either side unless the user asks for it. This keeps generation time, cost, and file size reasonable.

Running The Generator

Run the generator from the target project root, not from the skill directory. This lets the script read that project's .env and write outputs to that project's generated-designs/.

Use the script path for the active agent:

• Claude Code: ~/.claude/skills/design-bridge/scripts/generate_design_image.py
• Codex: $CODEX_HOME/skills/design-bridge/scripts/generate_design_image.py, usually ~/.codex/skills/design-bridge/scripts/generate_design_image.py

Example from Claude Code:

python3 ~/.claude/skills/design-bridge/scripts/generate_design_image.py \
  --prompt-file /tmp/design-prompt.md \
  --size 1024x1024 \
  --quality medium \
  --format webp \
  --compression 85 \
  --output-name design-draft

Example from Codex:

python3 ~/.codex/skills/design-bridge/scripts/generate_design_image.py \
  --prompt-file /tmp/design-prompt.md \
  --size 1024x1024 \
  --quality medium \
  --format webp \
  --compression 85 \
  --output-name design-draft

The script looks for OPENAI_API_KEY in the process environment first, then in .env in the current directory or a parent directory. It also accepts OPENAI_KEY and OPENAI_TOKEN as fallbacks.

For the API base URL, .env takes priority. If .env contains OPENAI_BASE_URL, the script uses that value before checking the process environment. Otherwise it falls back to https://api.openai.com/v1. The final request path is always <OPENAI_BASE_URL>/images/generations, so include /v1 in the base URL when the provider expects OpenAI-compatible versioned routes.

If the key is missing, ask the user to add this to the project .env:

OPENAI_API_KEY=sk-proj-...
# Optional:
OPENAI_BASE_URL=https://api.openai.com/v1

The script writes image files and a matching prompt file to generated-designs/ by default.

After the script prints the generated image path, try to run:

open path/to/generated-image.webp

Use the actual generated image path. If the command fails, continue by reporting the path clearly.

API Notes

The implementation follows the official OpenAI image-generation guide for the Image API:

• Default endpoint: POST https://api.openai.com/v1/images/generations
• Custom endpoint: set OPENAI_BASE_URL; .env wins over process environment.
• Required fields: model and prompt
• Useful fields for this skill: size, quality, n, output_format, output_compression
• gpt-image-2 accepts custom sizes when both edges are multiples of 16px, the long-to-short-edge ratio is at most 3:1, and total pixels are within the API limits.
• gpt-image-2 does not currently support transparent backgrounds.
• The response returns generated image data in the data array, normally as base64 image content.

Source checked: https://developers.openai.com/api/docs/guides/image-generation

Final Response

After generation, tell the user:

• The exact output image path.
• The prompt file path.
• Any non-default generation settings used.
• Whether opening the image with open succeeded.

Never print or expose the OpenAI API key.