generate-image

GEMINI_API_KEY

uv

Workflow

1. Understand — Determine mode (t2i, i2i, multi-reference), gather parameters (model, aspect ratio, resolution, output path). If the prompt requires precise execution (specific pose, asymmetric framing, exact crop), default to

   --batch 3

   or

   --batch 4

   and surface this to the user — image generation is stochastic and precise directives hit ~50% per seed. Exit: mode, parameters, and batch size are clear.
2. Craft prompt — Default to the minimal prompt that can carry the intent: t2i uses narrative prose; i2i/multi-reference uses a reference block plus the minimal directive. Apply the Core checklist (always, for the matching mode). Reach into the Escalation toolkit only on a known-hard signature — a detail/geometry-fidelity shot — or after a batch shows drift; then add only the specific lock for the attribute that is drifting, not the whole kit. Over-constraining a simple edit degrades it as surely as under-specifying a complex one. Exit: prompt written, Core items satisfied, escalation tools added only where a signature or observed drift justifies them.
3. Confirm — Show the user the exact prompt, input images (if any), model, resolution, aspect ratio, and batch size. Ask for confirmation. Exit: user approves.
4. Generate — Run the script with confirmed parameters. Exit: images are saved and displayed.
5. Iterate — Present results and evaluate against intent before offering refinements. Evaluation order by mode: t2i — subject correctness, composition, style fidelity. i2i edit — the changed element looks right, nothing else changed. Multi-reference composition — the primary transferred attribute matches its source reference FIRST (for a detail shot, the construction geometry — width, edge shape, count, angle), secondary consistency (identity, environment) holds SECOND, staging (lighting, composition, framing) THIRD. Decide what's primary per task. Cherry-pick the winning frame from the batch rather than re-prompting for consistency past ~75%. Exit: user is satisfied or moves on.

Default Output & Logging

~/Documents/generated images/

.md

logo.png

logo.md

Core Prompting Principle

Bad:  "cat, wizard hat, magical, fantasy, 4k, detailed"

Good: "A fluffy orange tabby sits regally on a velvet cushion, wearing an ornate
       purple wizard hat embroidered with silver stars. Soft candlelight illuminates
       the scene from the left. The mood is whimsical yet dignified."

Bad:   "A clean studio backdrop. No warm tones, no cream, no beige, no tan."
Good:  "A clean cool-neutral gray studio backdrop with subtle blue undertones."

Bad:   "A headshot with no harsh shadows on the face, no distracting background."
Good:  "A headshot on a clean neutral gray backdrop, even soft frontal fill light
        that flatters the face."

[Subject] doing [Action] in [Context]. [Camera/Composition]. [Lighting]. [Style]. [Constraint].

Advanced Prompting Techniques

Key Editing Principles

--input

References

• references/capability-patterns.md — mode-specific tips for photorealistic scenes, product photography, logos, stylized illustration, text rendering, and grounding
• references/editing-guide.md — edit grammar, reference blocks, directive structure, image ordering, semantic masking, character consistency
• references/style-reference.md — named aesthetics lexicon (film stocks, cameras, studios, artists, movements)

Configuration

Model Selection

Aspect Ratios

Resolutions

• 0.5K (~512px) — fast preview (Nano Banana only)
• 1K (~1024px) — default, fast
• 2K (~2048px) — high quality
• 4K (~4096px) — maximum detail

Thinking Mode (Nano Banana only)

• minimal (default) — fastest, suitable for straightforward prompts
• low/medium — balanced reasoning for moderately complex scenes
• high — maximum reasoning for complex multi-element compositions, precise text rendering, or intricate spatial layouts

--thinking high

Script Usage

# Text-to-image (t2i) — uses Nano Banana by default
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png

# Nano Banana Pro model
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png --model pro

# Image-to-image editing (i2i)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Make it sunset colors" --input photo.png --output edited.png

# Multi-reference composition
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Combine the cat from image 1 with the background from image 2" --input cat.png --input background.png --output composite.png

# With options (aspect ratio, resolution, thinking, batch, grounding, format)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Logo for 'Acme Corp'" --output logo.png --aspect 1:1 --resolution 2K --thinking high

Script Options

--prompt

-p

--output

-o

--input

-i

--model

-m

--aspect

-a

--resolution

-r

--grounding

-g

--image-grounding

--thinking

-t

--quality

-q

--format

-f

--batch

-b

--json

--quiet

Pre-Generation Checklist

Core — t2i (always)

• Narrative description (not keyword list)?
• Positive framing throughout — no "no X" / "not X" / "do not X" clauses anywhere in the prompt?
• Camera/lighting details for photorealism?
• Text in quotes, font style described? (if the image has text)
• Aspect ratio appropriate for use case?
• Model choice appropriate? (Nano Banana default; Nano Banana Pro for max quality)
• Thinking level set for complex prompts? (Nano Banana only)
• Batch size matches precision needs? (

  --batch 3

  or

  --batch 4

  for precise pose / framing / asymmetric directives)

Core — i2i / multi-reference (always)

• Reference block at start of prompt labeling each image's role?
• Reference roles positive-only — lists what to USE from each ref, never what to ignore? (see editing-guide.md "Reference Block")
• Minimal directive pattern? (Reference block + one Replace directive — no "do not change anything else" stop clause, no decorative preservation clauses)
• Positive framing throughout the directive? (no negation anywhere, including locks and composition clauses)
• Base image first in

  --input

  (Image 1), and prompt labels match input order? (mislabeled roles cause character drift)
• Only one change per prompt? (split competing directives into sequential passes)
• When extracting/transferring elements: explicitly named each element rather than generic "outfit/object from image X"?
• One reference carrying an element you need to preserve while another reference could compete with it? → add

  CRITICAL — [element]

  proactively: assign the source reference explicitly ("Image 1 is the sole identity source. Image 2 is scoped to [attribute] only."). Do not wait for drift — role competition defeats text directives silently.
• No color labels competing with reference image? (color words override visual reference — see editing-guide)
• Base image has minimal accessories that could contaminate? (bags, hats, sunglasses bleed into output)
• Reference count within model limits? (Nano Banana: 14, Nano Banana Pro: 11)
• For 3+ references: per-reference role-assignment sentence? (one sentence assigning each image its contribution — see editing-guide.md "Per-Reference Role Assignment")
• For photorealistic human shots: skin & finish locked? (the one near-universal CRITICAL section — generative skin drifts to plastic/retouched)

Escalation toolkit — reach for only on a hard signature or observed drift

• An attribute (identity, lighting/color, orientation, drape) drifting across the batch? Lock that specific attribute in its own

  ## CRITICAL —

  section, positively phrased — without over-constraining the stable ones. (see editing-guide.md "Constraint Locking with CRITICAL Sections")
• Detail shot whose construction won't hold? Geometry lock via per-attribute enumeration, not generic "match exactly". (see capability-patterns.md "Geometry Lock for Detail Shots")
• Nano Banana +

  --thinking high

  with 3+ references and weak adherence? Add the inventory preamble. ("Silently inventory the design-critical details: ...")
• Follow-up shot from the same set? Continuity assertion. ("from the same set as Image N: same subject, same setting, same light" — see editing-guide.md "Continuity Assertion")
• Campaign with a locked hero image? Collapse to two-input form — hero as bundle-source + the single new-attribute reference. (see editing-guide.md "Single-Reference Collapse")