---

name: image-gen description: "AI image generation: Gemini and Nano Banana backends; single/series/batch workflows with prompt-to-disk." agent: python-general-engineer user-invocable: false routing: category: image-generation triggers: - generate image - create image - image generation - AI image - gemini image - make image - draw - illustrate - sprite generation - card art - batch generation - series of images - character art - pixel art - image post-processing - make a picture - create art - generate a picture - make art - generate artwork - create artwork not_for: "HTML visualization or charts (use html-artifact), or deterministic non-AI palette/matrix pixel art (use game-asset-generator)" pairs_with: - python-general-engineer - game-dev

image-gen

Backend-agnostic image generation: single images, series with anchor-chain consistency, batch pipelines. Two backends: Gemini (API) and Nano Banana (local scripts with post-processing).

Deep References

| Signal | Load | Content | |---|---|---| | Gemini backend selected | references/backends/gemini.md | Models, env vars, flag table, examples, error codes | | Nano Banana needed (post-processing, series, JSON batch, style-match) | references/backends/nano-banana.md | Subcommands, flags, aspect ratios, prompt patterns by asset type |

Phase 1: Detect Backend

python3 skills/content/image-gen/scripts/detect-backend.py

• gemini -- load references/backends/gemini.md
• ask -- no key found; ask the user to set GEMINI_API_KEY

Gate: backend confirmed.

Phase 2: Write Prompt Files

Write all prompts to disk before any API call. Prompt files are the generation record and anchor-chain input for series.

File naming: single prompts/YYYY-MM-DD-{slug}.md, series prompts/{series-name}-01.md through -NN.md.

---
model: gemini-3-pro-image-preview
aspect-ratio: 1:1
flags: []
---

Full prompt text. Be explicit about subject, style, background, constraints.

mkdir -p prompts

For series: write ALL prompt files before calling any generation script.

Gate: all prompt files written and reviewed.

Phase 3: Select Script

| Use case | Script | Subcommand | |---|---|---| | Single image, Gemini | scripts/generate_image.py | --prompt | | Batch from text file, Gemini | scripts/generate_image.py | --batch | | Single with post-processing | scripts/nano-banana-generate.py | generate | | Style match from reference | scripts/nano-banana-generate.py | with-reference | | Batch from JSON manifest | scripts/nano-banana-generate.py | batch | | Series (anchor chain) | scripts/nano-banana-generate.py | generate then with-reference | | Post-processing only | scripts/nano-banana-process.py | crop / remove-bg / pipeline |

Model selection:

| Scenario | Model | |---|---| | Draft, testing, batch, cost-sensitive | gemini-2.5-flash-image (2-5s) | | Final asset, character art, typography | gemini-3-pro-image-preview (~30s) |

Aspect ratio by use case:

| Asset type | Ratio | |---|---| | Sprites, characters, icons | 1:1 | | Card art, landscape | 16:9 | | Vertical maps, portrait bg | 9:16 | | Portrait cards | 3:4 | | Wide banners | 21:9 |

Generate at the target ratio. Generating 1:1 and cropping to 16:9 loses 56% of pixels.

Gate: script and subcommand identified.

Phase 4: Generate

Use absolute paths for output files. Show full script output.

Anchor-Chain Algorithm (Series)

Character drift occurs when images are generated independently. Prevent it by passing the previous output as --reference:

image-01.png (no ref) -> image-02.png (ref=01) -> image-03.png (ref=02) -> ...

1. Generate image 1 with no reference.
2. Use output of image 1 as --reference for image 2.
3. Continue: each image N references image N-1.

Save originals with --save-original for any batch or expensive generation. Re-processing a saved original is free; re-generating costs quota and may break the chain.

Gate: script exits 0.

Phase 5: Verify and Report

Read the generated image to verify:

• Subject matches prompt
• No unwanted watermarks or artifacts
• Aspect ratio and framing correct
• No excessive padding or dark borders

If inspection fails: regenerate with adjusted prompt. Report the issue before retrying.

Report: output file path (absolute), dimensions, model, post-processing applied, verification result. Report only what was requested.

Error Handling

| Error | Cause | Resolution | |---|---|---| | GEMINI_API_KEY not set | Missing env var | export GEMINI_API_KEY=your_key | | No image in response | Safety filter or text-only response | Adjust prompt; remove policy-adjacent content | | Missing dependency: google-genai | Package absent | pip install google-genai pillow | | Rate limit exceeded (429) | Too many requests | Increase --delay; script retries automatically | | Content policy violation (400) | Restricted content | Rephrase using neutral language | | Model not found | Wrong model string | Use exact strings: gemini-2.5-flash-image or gemini-3-pro-image-preview |