imagine

What this skill does

# Image Generation Skill

Generates or edits images for the current project (e.g., website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, infographics). Defaults to **Google Gemini** (`gemini-3.1-flash-image-preview`) as the default provider, with **OpenAI** (`gpt-image-1.5`) available via `--provider openai` and **Recraft** (`recraftv4`) available via `--provider recraft`. Prefers the bundled CLI for deterministic, reproducible runs.

Run `python "$IMAGINE" generate --help` to see all available params for the current provider.

## CLI path setup

Set the path to the bundled CLI at the start of any image generation workflow:

```bash
export IMAGINE="$HOME/.claude/plugins/web/skills/imagine/scripts/image_gen.py"
```

All CLI invocations below assume `$IMAGINE` is set.

## When to use

- Generate a new image (concept art, product shot, cover, website hero)
- Edit an existing image (inpainting, masked edits, lighting or weather transformations, background replacement, object removal, compositing, transparent background)
- Style-guided generation or editing using a reference image (`--reference`)
- Batch runs (many prompts, or many variants across prompts)
- Craft, refine, or generate a structured image prompt without producing an image
- Analyze the visual style of a reference image (palette, texture, composition)
- Extract a reusable style from a reference image for consistent application across assets

## Reference image & style extraction

At the start of every generation workflow, **ask the user whether they have a reference image** they want to match stylistically. Do not skip this step.

If a reference image is provided:

1. **Determine the intended model first.** Use the provider selection decision tree (below) to identify which provider and model the final generation will use. The style extraction method depends on this choice.

   > **Default-path note:** The default Recraft model is V4, not V3. Unless the user explicitly requests V3 or `recraftv3`/`recraftv3_vector`, style references follow Path B (style prompt analysis). When using the default Recraft model, omit `--model` (it already defaults to the latest).

2. **Branch by model:**

   **Path A — Recraft V3 models** (`recraftv3`, `recraftv3_vector`):
   - Use `mcp__recraft__create_style` to extract a reusable style from the reference image.
   - Pass the returned `styleID` via `generate_image` MCP tool or `--style-id` CLI flag.

   **Path B — All other models** (Google Gemini, OpenAI, Recraft V4/V2):
   - Visually analyze the reference image yourself and produce a **style prompt** — a structured text description that captures the visual identity of the reference.
   - The style prompt must cover these dimensions (include only those that are distinctive/non-default):
     - **Medium/technique**: e.g., watercolor, digital illustration, oil painting, 3D render, vector flat
     - **Color palette**: dominant hues, saturation level, temperature (warm/cool), contrast
     - **Texture/surface**: smooth, grainy, painterly brushstrokes, halftone, noise
     - **Lighting**: direction, quality (soft/hard), color temperature, rim light, ambient
     - **Composition style**: symmetrical, rule-of-thirds, cinematic widescreen, centered
     - **Mood/atmosphere**: serene, dramatic, whimsical, gritty, ethereal
     - **Line quality**: clean/sketchy, thick/thin, visible outlines or not
     - **Rendering detail level**: minimal/stylized vs hyperdetailed/photorealistic
   - Present the style prompt to the user for confirmation.
   - Weave the confirmed style prompt into the structured prompt spec (under `Style/medium:`, `Lighting:`, `Color palette:`, `Materials/textures:`, `Vibe/mood:` fields).

3. Regardless of path, describe the extracted/analyzed style attributes back to the user (palette, texture, composition, mood) before proceeding.

If no reference image is provided, proceed directly to prompt crafting.

## Decision tree (provider -> generate vs edit vs batch)

### Provider selection

- If the user needs **mask-based editing** → `--provider openai`
- If the user needs **transparent background control** (`--background transparent`) → `--provider openai`
- If the user needs **fine-grained quality/compression/fidelity control** → `--provider openai`
- If the user needs **named artistic styles** (Illustration, Pop Art, etc.) → `--provider recraft`
- If the user needs **custom style ID from reference images** → `--provider recraft` with explicit V3 model (`recraftv3` or `recraftv3_vector`) — this is opt-in, not the default Recraft path
- If the user needs **style-matched generation from reference images with other providers** → analyze reference visually and encode as style prompt constraints
- If the user needs **vector/SVG output** → `--provider recraft` with a `_vector` model
- If the user needs **specific exact pixel dimensions** → `--provider recraft` (supports 14+ size presets)
- Otherwise → **Google** (default, no `--provider` flag needed)

### Command selection

- If the user provides an input image (or says "edit/retouch/inpaint/mask/translate/localize/change only X") → **`generate --image`**
- If the user wants to apply a reference style → add **`--reference`** to the command
- Else if the user needs many different prompts/assets → **`generate-batch`**
- Else → **`generate`**

All image inputs (`--image`, `--mask`, `--reference`) accept both local file paths and `https://` URLs.

## Workflow

1. **Ask for reference image** — Before anything else, ask whether the user has a reference image or style to match. Do not skip this step.
2. **Extract style** — If a reference is provided, determine the intended model first (step 3 may inform this). For Recraft V3: use `mcp__recraft__create_style` to get a `styleID`. For all other models: visually analyze the reference and produce a style prompt covering medium, palette, texture, lighting, mood, and line quality. Describe the extracted/analyzed style back to the user.
3. **Decide provider + command** — Use the decision tree to select provider and command based on the user's needs.
4. **Collect inputs** — Gather prompt(s), exact text (verbatim), constraints/avoid list, and any input image(s)/mask(s). For multi-image edits, label each input by index and role; for edits, list invariants explicitly.
5. **Craft structured prompt** — This is the **primary deliverable**. Augment the user's intent into a structured prompt spec (see Prompt augmentation section). Only make implicit details explicit; do not invent new requirements.
6. **Present prompt for review** — Show the structured prompt to the user for approval. If the request is **prompt-only** (no image generation needed), stop here and deliver the prompt.
7. **Execute generation** — Run the bundled CLI (`python "$IMAGINE" ...`) or Recraft MCP tools with sensible defaults. For batch runs, write a temporary JSONL, run once, then delete.
8. **Inspect & iterate** — For complex edits/generations, inspect outputs and validate: subject, style, composition, text accuracy, and invariants/avoid items. Make a single targeted change per iteration.
9. **Deliver** — Save/return final outputs and note the final prompt + flags used.

## Temp and output conventions

- Use OS temp directory via `tempfile.gettempdir()/imagine/` for intermediate files (for example JSONL batches); delete when done.
- Write final artifacts under `output/imagine/` when working in this repo.
- Use `--out` or `--out-dir` to control output paths; keep filenames stable and descriptive.

## Dependencies (install if missing)

Prefer `uv` for dependency management.

### Google provider (default)

```
uv pip install google-genai pillow
```

### OpenAI provider

```
uv pip install openai pillow
```

### Recraft provider

```
uv pip install openai pillow
```

(Same deps as OpenAI — uses openai SDK with custom base_url)

If `uv` is unavailable:

```
python3 -m pip install google-genai pillow   # Google
pyt