image-gen

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-sprite-pipeline"]}

image-gen

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

Reference Loading Table

Signal	Load These Files	Why
Every request (always load)	references/series-consistency.md	Anchor-chain and prompt-file-first rules apply to all generation
Every request (always load)	references/backend-selection.md	Mode decision required before every generation
Script output gemini	references/backends/gemini.md	Gemini API models, env vars, flags
Script output nano-banana	references/backends/nano-banana.md	Nano Banana subcommands, flags, aspect ratios

Phase 1: Detect Mode and Load References

Run the backend detection script — it reads environment variables and outputs a single word:

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

Output values:

• gemini — GEMINI_API_KEY or GOOGLE_API_KEY is set
• ask — no key found; ask the user which backend to use

Load references based on output:

1. Load references/series-consistency.md (always — applies to every generation).
2. Load references/backend-selection.md (always — needed to pick mode and script).
3. Load references/backends/gemini.md when output is gemini.
4. Ask the user to set GEMINI_API_KEY or confirm they want to use local scripts when output is ask.

Gate: references loaded, backend confirmed before Phase 2.

Phase 2: Write Prompt File

Write the complete prompt to disk before any API call. Prompt files serve as the generation record and the anchor-chain input for series — writing them first means the full intent is on disk before any quota is spent.

File naming:

• Single image: prompts/YYYY-MM-DD-{slug}.md
• Series: prompts/{series-name}-01.md, prompts/{series-name}-02.md, ...

Prompt file format:

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

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

Create the prompts/ directory if absent:

mkdir -p prompts

For a series, write all prompt files before calling any generation script. See references/series-consistency.md for the anchor-chain algorithm and why this ordering prevents drift.

Gate: all prompt files written and reviewed before Phase 3.

Phase 3: Select Mode and Script

Use references/backend-selection.md to map the request to the correct script and subcommand.

Use case	Script	Notes
Single image, Gemini	scripts/generate_image.py	--prompt flag
Batch from prompt file, Gemini	scripts/generate_image.py	--batch flag
Single or batch with post-processing	scripts/nano-banana-generate.py	Full flag set in backend ref
Series with anchor chain	scripts/nano-banana-generate.py with-reference	Load ref images from previous outputs
Post-processing only	scripts/nano-banana-process.py	crop, remove-bg, pipeline subcommands

Gate: script and subcommand identified before Phase 4.

Phase 4: Generate

Call the selected script with absolute paths for output files — relative paths break when scripts run from different working directories.

For series generation, follow the anchor-chain sequence from references/series-consistency.md:

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

Show the full script output — the user needs status messages, warnings, and partial failure information.

Gate: script exits 0 before Phase 5.

Phase 5: Verify and Report

Visual inspection is mandatory. Read the generated image file to verify:

• Subject matches the prompt
• No unwanted watermarks, logos, or artifacts
• Aspect ratio and framing are correct
• No excessive padding or dark borders that need cropping

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

Report to the user:

• Output file path (absolute)
• Image dimensions
• Model used
• Post-processing applied (if any)
• Visual verification result

Report only what was requested. The user did not ask for style suggestions or additional generations.

Error Handling

Error	Cause	Resolution
GEMINI_API_KEY not set	Missing env var	export GEMINI_API_KEY=your_key or export GOOGLE_API_KEY=your_key
No image in response	Prompt triggered safety filter or text-only response	Adjust prompt phrasing; check for policy-violating content
Missing dependency: google-genai	Package not installed	pip install google-genai pillow
Rate limit exceeded (429)	Too many API calls	Increase --delay; default 2s may be too aggressive on free tier
Content policy violation (400)	Restricted prompt content	Rephrase using neutral language; this restriction is API-side
No image data in response	API returned text only	Set response_modalities=["IMAGE", "TEXT"] in config