Image Generation

---
name: image-generation
description: "AI image generation for any product with OpenAI GPT Image (default) and Gemini, FLUX, Recraft, Ideogram or Seedream when they fit better: illustrations and characters, storybook and app art, marketing and share images, backgrounds and plates, storyboard frames, keyframes for image-to-video, and cutout elements for motion graphics. Writes structured prompts with a locked style suffix, keeps characters, palette and style consistent across 20 to 50 images with cast sheets and references, sizes images for camera moves, makes clean cutouts, reviews its own output like a hostile art director, controls cost, and keeps generated content honest and legally safe. Use it whenever the user wants to generate, edit, restyle, cut out or review AI images, mentions gpt-image, DALL-E, Nano Banana, Midjourney, FLUX or \"make an illustration\", or asks for consistent characters or a visual style, even if they don't say \"image generation\". The video-director skill calls it for film assets."
---

# Image generation

Images made for a product are props with a job (an app card, a share image, a plate the camera moves across), not posters.
Model ids churn monthly: check `references/models.md` dates and the vendor changelog before a new project.

## Step 0: read every file before the first action

This skill is loaded whole, never in part. Read this `SKILL.md` to the end, then every file in the table below, each to
its last line: no `offset`/`limit`, no `head`, `grep` or skimming, no "only the sections this task needs". If a read comes
back truncated, keep reading until the file ends. The task decides what you apply, never what you read; the table says
where each topic lives, not which files to skip. This holds when the skill is called on its own, from `video-director`, or
by a sub-agent. If the context is summarised mid-task, read the set again before the next action that depends on it.

| Topic | File |
|---|---|
| Prompt anatomy, the style suffix, edit prompts, negatives per model, style recipes by format | `references/prompting.md` |
| OpenAI API facts (models, sizes, quality, background, masks, cost), the model chooser | `references/models.md` |
| Cast sheets, descriptor strings, drift checks, palette locking, style across a set | `references/consistency.md` |
| Sizes and overscan, light continuity, layers, cutouts, sharpness, image-to-video keyframes | `references/motion-assets.md` |
| Reviewing your own images, failure table, brief-to-handoff workflow, cost control | `references/review.md` |
| Ownership, indemnity, people, disclosure, provenance | `references/legal.md` |
| Script flags, the prompts-file schema, other providers' keys | `scripts/README.md` |

## Ten rules

1. Generate at the final aspect, with margin for any camera move, one subject per file when it moves independently, and
   never with text, logos or UI painted in. Leave surfaces that will carry real text blank ("the card is plain white with
   nothing on it") and composite the real thing in code.
2. **Lock a style suffix** once (medium, construction, palette names with hex values, light direction, "no text, no logos,
   no border") and append it verbatim to every prompt. Only the subject block varies. Version it if it must change.
3. **Cast first.** One approved character sheet on a plain background; every scene is an edit that passes the sheet as
   Image 1 with each character's locked descriptor string repeated word for word. Never route identity through earlier
   scene images or rejects.
4. Describe observable choices (camera height, lens feel, light direction, materials, counts, gaze, who holds what), never
   "epic, cinematic, stunning, 8k". Mood becomes light and colour; prestige becomes physical detail.
5. Disambiguate by physical traits, not names: "a plump hen sitting, small red comb, clearly a hen and not a rooster" fixed a
   rooster. State gender for gendered nouns; models defaulted "teacher" and "doctor" to women.
6. Say what you want first, then name the specific intrusion ("no lettering on the sign"). On models without negative
   support (FLUX, Gemini) write positives only. A constraint that keeps failing gets stated three ways.
7. **Cutouts**: native alpha only on a model that documents it today (gpt-image-2.5 family with no backdrop words in the
   prompt), otherwise pure white with "no floor shadow" and matte with BiRefNet (grey or green backdrop when the subject has
   white in it). Verify alpha in code; review over a saturated colour, never over white.
8. Draft cheap (low quality, many variants, a contact sheet), finalise expensive only for picks. Keep every version and a
   sidecar with the exact prompt, model, size and references.
9. **Review like a hostile art director**: contact sheet first, then zoom on hands, faces, stray text, palette drift, scale
   between characters, light direction. A pretty image that misses the brief fails. Vision judges hallucinate defects:
   crop and check the pixels before acting.
10. **Generated imagery is never evidence**: no real people, no generated product renders passed off as photos, no fake
    screenshots or events. Real product = real screenshots and photos, composited. Never name living artists or trademarked
    characters. For children's products, check provider terms (the Gemini API terms bar apps likely to be used by minors).

## Workflow

1. **Brief**: delivery sizes, shot or asset list with each image's job (plate, cutout, keyframe, card), style references,
   surfaces that will carry real text.
2. **Explore**: 3 to 4 style directions, each one suffix applied to the same two test subjects, low quality, several
   variants, one labelled contact sheet; pick with the owner.
3. **Lock**: suffix (versioned), palette, light direction, backdrop line; approve the cast sheet (and a prop or set sheet) at
   high quality.
4. **Batch** from a prompts file, references first, 2 to 4 requests in flight, never overwriting.
5. **Review** (`review.md` checklist), then **fix**: edit when composition and identity are right and one local thing is
   wrong (one change per edit, restate what to preserve); regenerate when composition, identity or style is wrong, or after two
   failed edits; make pixel-exact fixes by compositing in code.
6. **Cut out and QA** edges at 200% over a saturated colour.
7. **Hand off** trimmed PNGs with a manifest of native size and anchor point; keep prompts next to the images.

## Scripts

**Paths:** scripts live in this skill's `scripts/` folder, under the base directory shown when the skill loads (`~/.claude/skills/image-generation/` for a standard install; a plugin install puts it elsewhere). The other skills of this suite sit next to it as sibling folders. Paths written as `~/.claude/skills/...` below assume the standard install.

uv scripts with `--help` and `--dry-run`; keys from `OPENAI_API_KEY` (other providers in `scripts/README.md`) or
`--env-file`. Path: `~/.claude/skills/image-generation/scripts/`. Full flags and the prompts-file schema:
`scripts/README.md`; a product-neutral example prompts file: `assets/image_prompts.example.json`.

```
gen_image.py PROMPTS.json [NAMES...] [--out public/img] [--provider openai|gemini|bfl|recraft] [--model ID] [--quality Q]
    [--final|--draft] [--aspect 16:9|9:16|1:1|4:5] [--overscan F] [--composite-back] [--regenerate] [--concurrency 2]
    [--budget USD] [--batch] [--contact-sheet PNG] [--env-file PATH] [--dry-run]
gen_image.py pick NAME LETTER [--dir public/img]
gen_image.py contact-sheet IMAGES... --out PNG
gen_image.py check-alpha IMAGES...
gen_image.py batch-fetch BATCH_ID [--out public/img]
cutout.py IMAGES... [--out-dir DIR] [--check-dir DIR] [--backdrop auto|#RRGGBB] [--erode PX] [--feather PX] [--margin 12] [--json]
```

- Defaults: `gpt-image-2.5-flare` for drafts, `--final` = `gpt-image-2.5-sunburst` at high quality; `--draft` = low quality,
  4 variants at ~1 MP into `drafts/`, then `pick NAME b` promotes one. `gpt-image-1` is refused from 2026-10-23.
- `background: transparent` is sent only to the 2.5 family and the output is checked for real alpha (kept but marked FAIL
  if missing); backdrop words in the prompt or style override the parameter. Otherwise white (or `grey`, `green`,
  `color:#hex`, `none` for plates) and `cutout.py`.
- References as `{"ref": "cast", "role": "identity and outfits"}` write the "Image N: …" lines for you, identity first;
  `edit_of` iterates on a previous output. Masks apply to Image 1 (white = edit) and are guidance only: `--composite-back`
  makes the edit pixel-exact.
- Every output gets a sidecar (prompt, model, size, references with hashes, usage, request id, cost, style hash); the script
  warns when a set mixes style hashes. Moderation blocks are never retried; 429/5xx are. `--batch` halves the price for
  large non-urgent sets.
- The Gemini, FLUX and Recraft adapters follow the vendors' documented formats but haven't been run live: check the first
  real result by hand. Gemini and FLUX take positive prompts only. Recraft supports text-to-image only here.
- `cutout.py` auto-detects the backdrop, removes the white halo by edge-colour decontamination, warns when the subject
  shares the backdrop colour or has enclosed holes, skips matting for files that already have alpha, and writes review
  copies over violet `#8342C9`.