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 the caller has a preferred image engine. The hint selects that engine only. It does not pretend every installed command has a standalone image subcommand.

• Imagen: calls the imagen CLI directly.
• Grok: calls grok-img, the noninteractive xAI image CLI. The plugin normalizes the generated image to the requested output path.
• Codex: starts a Codex agent and asks it to use image_gen when that host exposes the tool.

Grok and Codex must write the requested PNG. A prose-only Codex result or a missing grok-img result fails closed and leaves the generated prompt sidecar for a manual retry. With no hint, auto tries each installed engine in order and falls through after a failed attempt, which lets an unauthenticated Imagen install reach another configured engine.

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 Grok image CLI

The --engine-hint grok adapter uses the noninteractive grok-img command, not Grok Build's interactive /imagine TUI. It needs Node.js 20.19 or newer and an xAI account with image-generation access.

npm install -g grok-image-cli
grok-img --version
grok-img auth login

Alternatively, configure the key noninteractively before running the skill:

export XAI_API_KEY="xai-..."

grok-img writes to a staging directory; generate.py selects its one result and copies it to the exact --output path.

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)

--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."

# Ask grok-img to generate with the configured xAI account.
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 backend, policy, model. Prompt sidecar 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 (backend, policy, model)

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