image-gen

Image Gen

Article image skill. Not the diagram renderer (that is imagen-diagrams).

When to fire

Use this skill when the user wants a cover image, in-article illustration, or visual assets for an article.

Do not use this skill to render Mermaid or PlantUML. Send those to imagen-diagrams.

Image-engine hint and backend (auto)

Use --engine-hint imagen, --engine-hint grok, or --engine-hint codex when a caller has a preferred image engine. The hint chooses a real execution path, not a guessed subcommand.

• Imagen calls the imagen CLI directly.
• Grok calls grok-img, the noninteractive xAI image CLI, then normalizes its generated file to the requested output path.
• Codex starts a Codex agent and asks image_gen to save the requested PNG.

Grok and Codex must actually create the file. A prose-only Codex response or a missing grok-img result fails closed, leaves the prompt sidecar, and records the failed attempt. With no hint, auto tries every installed engine in this order and continues after a runtime or authentication failure.

1. imagen CLI if on PATH. Brace policy: imagen-cli-vars (double braces).
2. Then grok-img CLI. Brace policy: grok-imagine (no rewrite).
3. Else codex CLI. Brace policy: grok-imagine (no rewrite).
4. Else fail closed. Write <stem>_imagen.prompt.txt and exit 2.

Never invent a PNG. If no worker is installed, keep the prompt sidecar and tell the user to run /image-gen-install.

Install the imagen CLI

Latest gemini-imagen (imagen on PATH) plus Nano Banana model pin:

python3 skills/image-gen/scripts/install_imagen.py

Pins gemini-3.1-flash-image (Nano Banana 2) as the CLI default. Cover images use Nano Banana Pro unless the user asks otherwise.

Needs GOOGLE_API_KEY or imagen keys set google YOUR_KEY.

Models (Nano Banana, August 2026)

Alias	Model ID	When
nano-banana-2 (default)	gemini-3.1-flash-image	Article diagrams, high-volume art. 0.5K–4K.
nano-banana-pro	gemini-3-pro-image	Covers, in-image text, dense composition.
nano-banana-2-lite	gemini-3.1-flash-lite-image	Drafts and thumbnails.
nano-banana	gemini-2.5-flash-image	Legacy fallback.

--kind cover selects Pro. --kind article selects Nano Banana 2.

Workflow

1. Analyze the article

List 2–4 images (1 cover + 1–3 in-article). One concept per in-article image.

2. Generate the cover

Metaphorical, high-impact, 16:9.

python3 skills/image-gen/scripts/generate.py \
  --kind cover \
  --aspect 16:9 \
  --output work/images/article_cover.png \
  --prompt "A stunning digital art cover image of [metaphor] representing [topic]. Cinematic lighting, professional, high-detail. Style: conceptual 3D render."

3. Generate in-article images

Direct, labeled, one concept.

python3 skills/image-gen/scripts/generate.py \
  --kind article \
  --aspect 16:9 \
  --output work/images/article_workflow.png \
  --prompt "A clean technical diagram showing [concept] with color-coded arrows and clear labels. Style: blueprint, professional."

# Prefer the noninteractive grok-img CLI. Configure XAI_API_KEY or run
# `grok-img auth login` first.
python3 skills/image-gen/scripts/generate.py \
  --kind article \
  --engine-hint grok \
  --aspect 16:9 \
  --output work/images/article_workflow.png \
  --prompt "A clean technical diagram showing [concept]."

4. Integrate + ALT text

Cover immediately after H1. In-article images at section breaks. ALT text 50–125 characters, specific, no "image" / "diagram" alone.

![Architecture diagram showing Cloud Run connecting through a VPC connector to AlloyDB](images/article_cover.png)

5. Verify

PNG exists. Sidecar *.json records engine hint, backend, policy, model, and every attempted engine. Prompt sidecar is kept next to the PNG.

Scripts

From skills/image-gen/scripts/:

• generate.py — write prompt, apply brace policy, call worker, fail closed
• install_imagen.py — pip install -U gemini-imagen and pin Nano Banana 2
• backends.py — PATH detect + brace policy
• models.py — Nano Banana catalog

Compatibility: imagen generate "PROMPT" -o FILE.png still works if imagen is on PATH. Prefer generate.py so grok/codex fallback and fail-closed behavior stay intact.

Prompt craft

Load references/prompting_guide.md when the prompt is non-trivial.

Cover: [Style] cover image of [metaphor] representing [topic], [atmosphere], [composition].

In-article: [Style] showing [one concept], [elements], [labels].

Nano Banana Pro renders in-image text more reliably than Flash. Ask for "clear labels" only when using Pro, or keep labels short.

Outputs

• <stem>.png (or the --output path)
• <stem>_imagen.prompt.txt (always)
• <stem>.json sidecar (engine hint, backend, policy, model, attempts)

If the worker is missing, only the prompt sidecar is written and the process exits 2.