/image-generation

name: image-generation
description: Generates professional AI images using Google Gemini. ALWAYS invoke this skill when building websites, landing pages, slide decks, presentations, or any task needing visual content. Invoke IMMEDIATELY when you detect image needs - don't wait for the user to ask. This skill handles prompt optimization and aspect ratio selection.

Image Generation Skill

Generate professional AI images using Google Gemini via the bundled CLI script.

When to Invoke This Skill

Invoke immediately when:

**Web Development**

• Hero sections without images
• Feature illustrations needed
• Placeholder images in code (`placeholder.jpg`, `stock-photo.png`)
• Empty visual sections (`<section class="hero">` without images)
• Landing pages and marketing sites

**Presentations & Documents**

• Cover images and headers
• Conceptual diagrams
• Section dividers

**Applications**

• Onboarding illustrations
• Empty state graphics
• Error page visuals

Using the CLI

Run the bundled CLI script via bash:

node "${CLAUDE_PLUGIN_ROOT}/mcp-server/build/cli.bundle.js" \
  --prompt "Your detailed image description" \
  --output "./path/to/output.png" \
  --aspect-ratio "16:9"

`CLAUDE_PLUGIN_ROOT` is only set when the skill comes from the plugin. When the skill was copied into `~/.claude/skills` instead, run the `media-pipeline-cli` command with the same flags; it is installed with `npm install -g ./mcp-server` from a clone of the repository:

media-pipeline-cli --prompt "Your detailed image description" --output "./path/to/output.png"

Parameters

| Flag | Required | Default | Description | |------|----------|---------|-------------| | --prompt, -p | Yes | - | Detailed image description | | --output, -o | No | auto-generated | Output file path | | --aspect-ratio, -a | No | 1:1 | 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2 | | --model, -m | No | provider default | Model to use; routes the provider (gpt-image* → OpenAI, others → Gemini). dall-e* shut down on 2026-05-12 and is rejected | | --reference-images, -r | No | - | Reference image paths (PNG/JPEG/WebP, repeatable or comma-separated, max 5) | | --mask | No | - | PNG mask marking the region to repaint; OpenAI only, requires --reference-images | | --background, -b | No | provider default | auto, transparent or opaque; OpenAI only. `gpt-image-2` refuses `transparent` and is rejected before the request is sent | | --output-format, -f | No | provider default | png, jpeg, webp, gif (animated) or svg (vector); OpenAI only. Only png and webp take a transparent background; svg cannot be combined with --reference-images, and gif cannot be combined with --mask | | --complexity | No | model default | low, medium or high planning effort, separate from quality; OpenAI only. The 2.6 models default to high | | --frame-count | No | 9 | GIF frames, 2–16; requires --output-format gif. The frames share one sheet limited to 3840 px per edge and to 3840x2160 worth of pixels, so 16 frames need --size 720x720 or smaller (1024x1024 and 960x960 were refused, 720x720 worked) | | --size | No | from --aspect-ratio | Exact OpenAI size, WIDTHxHEIGHT or auto, overriding --aspect-ratio. Refused unless both sides are multiples of 16, neither edge exceeds 3840, and the ratio is between 1:3 and 3:1 | | --frame-duration-ms | No | 200 | Delay per GIF frame, 20–2000 ms; requires --output-format gif | | --svg-model | Depends on the account | - | Model that turns the reference image into the SVG, such as `gpt-5.5`; requires --output-format svg. Accounts with SVG model selection must pass it (the API answers "SVG generation requires 'svg.model'"); accounts without it must leave it out. SVG took about 2.5 minutes in testing, so pass `--timeout-ms 180000`. Claude Desktop stops a tool call at 240 seconds | | --svg-reasoning-effort | No | author model default | none, minimal, low, medium, high, xhigh or max; requires --svg-model | | --output-dir, -d | No | current directory | Output directory |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GEMINI_API_KEY | At least one of GEMINI_API_KEY / OPENAI_API_KEY | Your Gemini API key | | OPENAI_API_KEY | At least one of GEMINI_API_KEY / OPENAI_API_KEY | Your OpenAI API key | | GEMINI_DEFAULT_MODEL | No | Preferred default Gemini model | | OPENAI_DEFAULT_MODEL | No | Preferred default OpenAI model (default: gpt-image-2) | | IMAGE_PROVIDER | No | gemini or openai — provider used when --model is omitted | | REQUEST_TIMEOUT_MS | No | Request timeout in milliseconds for both providers (default 60000). GEMINI_REQUEST_TIMEOUT_MS is still read when this is unset. Use 180000 for SVG | | MEDIA_PIPELINE_LOG_LEVEL | No | Logging level for stderr diagnostics |

Output

The CLI outputs JSON:

{"success": true, "filePath": "/path/to/generated-image.png"}

Or on error:

{"success": false, "error": "Error message"}

Aspect Ratio Selection

• **16:9** - Hero images, website headers, presentations
• **1:1** - Social media, thumbnails, profile images
• **9:16** - Mobile stories, vertical banners
• **4:3** - Blog posts, general web content
• **3:2** - Photography-style images

Prompt Crafting

Use this formula for effective prompts:

[Style] [Subject] [Composition] [Context/Atmosphere]

Examples

**Hero Image for Tech Startup**

Minimalist 3D illustration of abstract geometric shapes floating in space,
soft gradient background from deep purple to electric blue, subtle glow effects,
modern professional aesthetic, wide composition for website header

**E-commerce Product**

Clean product photography of modern wireless headphones on white marble surface,
soft studio lighting from left, subtle shadows, high-end minimalist aesthetic,
centered composition

**Blog Post Header**

Aerial photography of winding river through autumn forest, golden hour lighting,
warm color palette with oranges and reds, cinematic wide s