Gemini

Step 1: Detect Capability

When a user makes a request, identify which capability matches. See capabilities.md for the full reference.

Step 2: Clarify (Always Ask)

Always ask clarifying questions, even if the request seems clear. Each capability has specific required information.

Questions should be conversational, not form-like. Examples:

• "What style are you going for - photorealistic, illustration, or something else?"
• "Which image has the face you want to use, and which has the body/pose?"
• "Should I keep the original background or use something new?"
• "Should the output match the aspect ratio of the original image?"

Reference capabilities.md for capability-specific questions.

Aspect Ratio Handling

For multi-image operations, default to preserving the target/base image's aspect ratio.

Default behavior by capability:

Workflow:

1. Auto-detect dimensions of the appropriate source image:

   file "/path/to/body_image.png"
   # Returns: ... 1080x799 ...
   

2. Calculate ratio (width ÷ height) and map to closest supported:

   Calculated	Closest	Flag
   ~1.0	Square	--aspect 1:1
   ~1.33	Landscape	--aspect 4:3
   ~0.75	Portrait	--aspect 3:4
   ~1.78	Widescreen	--aspect 16:9
   ~0.56	Vertical	--aspect 9:16
   ~2.33	Ultrawide	--aspect 21:9

3. Include in structured breakdown - show the detected ratio and confirm with user.

Example for face swap:

Body image: astronaut.jpg (1920x1080) → 16:9 widescreen
→ Using --aspect 16:9 to match body image dimensions

User can override with:

• "use 1:1 instead"
• "make it square"
• "change to portrait"

Step 3: Confirm (Structured Breakdown)

After gathering information, present a structured breakdown for approval:

## Request Analysis

**Capability**: [detected capability]

### Images Identified
| Role | File | Purpose |
|------|------|---------|
| [role] | `[filename]` | [what it provides] |

### Generated Prompt
[The full prompt that will be sent to the API]

### Parameters
- Model: `[model name]`
- Aspect: [ratio]
- [other relevant params]

### Command Preview
python3 .claude/skills/gemini/scripts/generate_image.py "[prompt]" [flags]

---
**Ready to generate?** Reply "yes" to proceed, or tell me what to change.

Step 4: Refine or Execute

If user says "yes": Execute the command.

If user requests changes: Update the breakdown and present again. Common refinements:

• "Change the model to Pro"
• "Make the prompt more specific about [X]"
• "Swap the image roles"
• "Add --thinking 16384"

Continue refining until the user approves.

Bypass Mode

Users can skip the structured approval workflow by including bypass phrases in their request.

Bypass Triggers

If the user's message includes any of these (case-insensitive), execute directly without the structured breakdown:

• "just do it", "just generate", "go ahead"
• "skip approval", "skip confirmation", "no confirmation needed"
• "don't ask", "don't confirm"
• "quick", "fast" (when combined with a clear, specific request)

Bypass Behavior

When bypassed:

1. Still detect the capability internally
2. Still apply best practices (appropriate model, aspect ratio)
3. Execute immediately without showing the structured breakdown
4. After generation, still offer: "Would you like any changes?"

Examples

Bypassed: "Just generate a cute robot holding a coffee cup" → Execute directly, show result, offer refinements

Not bypassed: "Generate a robot" (ambiguous, needs clarification) → Follow normal workflow, ask about style/details

Bypassed: "Quick headshot of this photo, skip approval" + image → Execute with sensible defaults (Pro model for headshots, appropriate aspect)

Example Interaction

User: "Do a face swap with these two photos"

Claude: "I can help with that face swap! A few quick questions:

• Which image has the face you want to transfer?
• Which image has the body/pose you want to use?
• Should I preserve any accessories (glasses, earrings) from the face source?"

User: "First image is my face, second is the astronaut. No accessories."

Claude:

## Request Analysis

**Capability**: Face Swap

### Images Identified
| Role | File | Purpose |
|------|------|---------|
| Face source | `photo1.jpg` | Face to transfer |
| Body target | `astronaut.jpg` | Body/pose to use |

### Generated Prompt
{
  "task": "Transfer face from Image 1 onto astronaut body in Image 2",
  "from_image_1": {
    "extract": ["face", "facial features", "expression", "skin tone"]
  },
  "from_image_2": {
    "keep": ["astronaut suit", "pose", "space background", "helmet framing"]
  },
  "integration": {
    "neck_blend": "seamless",
    "lighting": "match harsh space lighting from Image 2"
  }
}

### Parameters
- Model: `gemini-3-pro-image-preview` (recommended for face swaps)
- Aspect: 1:1

### Command Preview
python3 .claude/skills/gemini/scripts/generate_image.py '{...}' --image photo1.jpg --image astronaut.jpg --model gemini-3-pro-image-preview

---
**Ready to generate?** Reply "yes" to proceed, or tell me what to change.

User: "Add more thinking budget"

Claude: Updates breakdown with --thinking 16384 and presents again

User: "yes"

Claude: Executes the command

Quick Start

# Generate new image
python3 .claude/skills/gemini/scripts/generate_image.py "a cute robot"

# Edit existing image (conversational)
python3 .claude/skills/gemini/scripts/generate_image.py "add a red hat" --image ./generated_images/robot.png

# High quality with Pro model
python3 .claude/skills/gemini/scripts/generate_image.py "detailed portrait" --model gemini-3-pro-image-preview --thinking 16384

Conversational Workflow

This is the core workflow. Treat image generation as a dialogue with a creative partner.

Note: All generations must go through the Interactive Workflow above. The steps below describe the conversation after the user has approved execution.

New Generation

1. Understand the request - Clarify subject, style, mood if ambiguous
2. Offer prompt enhancement - Suggest improvements with visual details
3. Generate - Run the script
4. Present & iterate - Show result, ask "Would you like any changes?"

Editing (The Key Feature)

When user asks to modify a recent generation:

# User: "Make it brighter"
python3 .claude/skills/gemini/scripts/generate_image.py "make the image brighter with more sunlight" \
  --image ./generated_images/previous_image.png

# User: "Add a coffee cup"
python3 .claude/skills/gemini/scripts/generate_image.py "add a steaming coffee cup to the scene" \
  --image ./generated_images/previous_image.png

Example conversation flow:

User: Generate a robot
Claude: [generates robot, saves to generated_images/gemini_image_20251231_xxx.png]
        Here's your robot! Would you like any changes?

User: Make it hold a coffee cup
Claude: [uses --image flag with previous image]
        python3 ... "add a coffee cup to the robot's hands" --image ./generated_images/gemini_image_20251231_xxx.png
        Done! The robot now has a coffee cup. Anything else?

User: Change background to sunrise
Claude: [uses --image with the updated image]
        Updated with a sunrise background!

When to Use Each Mode

Reference Images (Style/Pose Transfer)

Pass multiple images with --image flags and describe the relationship in the prompt:

# Pose/expression transfer
python3 .claude/skills/gemini/scripts/generate_image.py \
  "Make the person in the first image adopt the pose and expression of the person in the second image" \
  --image subject.png --image reference.png

# Style transfer
python3 .claude/skills/gemini/scripts/generate_image.py \
  "Apply the artistic style of the second image to the first image" \
  --image photo.png --image artwork.png

# Identity swap
python3 .claude/skills/gemini/scripts/generate_image.py \
  "Put person A's face on person B's body" \
  --image personA.png --image personB.png

Tips for reference mode:

• First image is typically the subject/target
• Second image provides the style/pose/reference
• Be explicit in the prompt about what to transfer
• Pro model (--model gemini-3-pro-image-preview) works better for complex transfers

For comprehensive face swap techniques (4 swap types, 6 failure fixes, source image selection), see examples/advanced-techniques.md#face--identity-swaps.

Use Cases

Quick reference for common applications. See examples/prompts.md for full templates.

Model Selection

Reference: See config.md for current model IDs, rate limits, and parameters.

Choose based on use case:

Default: gemini-2.5-flash-image (Nano Banana) - good for most cases

Aspect Ratio Guide

Choose aspect ratio based on intended use:

Tip: Use 1:1 for lowest token cost; use 21:9 for cinematic shots.

Thinking Budget (Pro Model Only)

The --thinking parameter controls reasoning depth for gemini-3-pro-image-preview:

# Complex scene with maximum thinking
python3 .claude/skills/gemini/scripts/generate_image.py \
  "A detailed medieval marketplace with merchants, customers, and goods" \
  --model gemini-3-pro-image-preview \
  --thinking 16384

Rate Limits & Quotas

Free Tier:

Paid Tier (varies by spend):

• Tier 1: 500+ RPM
• Tier 2: 1,000+ RPM
• Tier 3: 2,000+ RPM

Cost Estimates:

• ~1,290 tokens per image (varies by complexity)
• ~$0.039 per image (varies by model/region)

Cost Optimization:

1. Use Flash for iterations, Pro for final output only
2. Use 1:1 aspect ratio when possible (lowest tokens)
3. The script auto-retries on rate limit (429) with backoff

Parameters

Output Format

The script returns JSON:

{
  "success": true,
  "prompt": "the prompt used",
  "model": "gemini-2.5-flash-image",
  "mode": "generate | edit | reference",
  "source_images": [],
  "aspect_ratio": "1:1",
  "thinking_budget": null | 8192,
  "images": ["path/to/output.png"],
  "text_response": "optional model commentary",
  "count": 1
}

Mode values:

• generate - No input images (0)
• edit - Single input image (1)
• reference - Multiple input images (2+)

Prompt Enhancement

Always offer to enhance basic prompts:

Enhancement techniques:

• Subject clarity (specific details)
• Style (photorealistic, illustration, oil painting)
• Lighting (golden hour, dramatic, soft)
• Composition (close-up, wide angle)
• Mood (serene, energetic, mysterious)
• Quality markers (8K, detailed, professional)

Prompt Engineering Best Practices

JSON-Structured Prompts (Recommended)

For complex generations, use JSON to organize your prompt. This improves consistency and makes prompts reusable:

{
  "subject": {
    "description": "A young professional woman",
    "age": "early 30s",
    "expression": "confident, approachable",
    "clothing": "navy business suit, white shirt"
  },
  "photography": {
    "style": "professional headshot",
    "camera": "Sony A7III, 85mm f/1.4",
    "lighting": "three-point studio lighting with soft key light"
  },
  "background": {
    "setting": "solid dark gray studio backdrop",
    "effects": "subtle vignette, slightly lighter behind subject"
  },
  "quality": "8K, natural skin texture with visible pores, catchlights in eyes"
}

When to use JSON:

• Multi-element compositions with many details
• Reusable templates (swap values, keep structure)
• Complex style/lighting/camera specifications
• Face preservation with outfit or background changes
• When you need to iterate on specific elements

When plain text works fine:

• Simple generations ("a cute robot")
• Quick edits ("make it brighter")
• Single-focus prompts

Face Preservation Pattern

Critical for transformations that should maintain identity:

{
  "face": {
    "preserve_original": true,
    "instruction": "Keep facial features 100% accurate from reference image"
  },
  "changes": {
    "clothing": "professional navy suit with white shirt",
    "background": "clean studio backdrop",
    "lighting": "soft professional lighting"
  },
  "do_not_modify": ["facial features", "expression", "face shape"]
}

Era-Specific Aesthetics

Reference specific time periods for authentic looks:

Advanced Techniques

Composition Rescue (Outpainting)

Expand images to different aspect ratios while maintaining visual coherence:

python3 .claude/skills/gemini/scripts/generate_image.py \
  "Expand to 16:9 aspect ratio. Seamlessly extend the scenery on both left and right sides. Match the original lighting, weather, and texture perfectly. Complete any cut-off objects naturally." \
  --image ./cropped_photo.png \
  --aspect 16:9

Smart Inpainting (Object/Crowd Removal)

Remove unwanted elements and fill with contextually appropriate content:

python3 .claude/skills/gemini/scripts/generate_image.py \
  "Remove all tourists/people in the background behind the main subject. Replace them with realistic background elements that fit the scene. Ensure no blur artifacts remain." \
  --image ./crowded_photo.png

Recursive/Droste Effect

Create images containing themselves infinitely:

python3 .claude/skills/gemini/scripts/generate_image.py \
  "Recursive image of an orange cat sitting in an office chair holding an iPad. On the iPad is the same cat in the same scene holding the same iPad. Repeated on each iPad." \
  --model gemini-3-pro-image-preview --thinking 16384

Virtual Model Try-On

Dress a model in specific garments while preserving fabric details:

python3 .claude/skills/gemini/scripts/generate_image.py \
  '{
    "task": "Using the garment from Image 1 and the model from Image 2, create a realistic full-body fashion photo",
    "fit_details": "Garment must drape naturally, creating realistic folds and wrinkles",
    "preservation": "Preserve original fabric texture, color, and logos with extreme accuracy",
    "integration": "Match ambient lighting, color temperature, and shadow direction",
    "style": "Clean e-commerce lookbook, Canon EOS R5, 50mm f/1.8"
  }' \
  --image garment.png --image model.png \
  --model gemini-3-pro-image-preview

Whiteboard to Professional Diagram

Convert hand-drawn sketches to polished business graphics:

python3 .claude/skills/gemini/scripts/generate_image.py \
  "Convert this hand-drawn whiteboard sketch into a professional corporate flowchart. Use minimalist McKinsey-style aesthetic: clean lines, ample whitespace, blue-and-gray palette. Align all boxes to a strict grid. Connect with straight orthogonal arrows. Transcribe labels into bold sans-serif font." \
  --image whiteboard_sketch.png

Text-Heavy Image Generation

For images requiring legible text (posters, infographics):

python3 .claude/skills/gemini/scripts/generate_image.py \
  '{
    "layout": "promotional poster",
    "text_elements": {
      "title": {"content": "Autumn Special", "style": "elegant gold serif, top center"},
      "offer": {"content": "Buy One Get One Free", "style": "modern badge/sticker"},
      "footer": {"content": "Limited Time Only", "style": "small clean text"}
    },
    "background": "cinematic close-up of steaming cappuccino, rustic wooden table, autumn leaves",
    "quality": "ensure all text is perfectly spelled, centered, and integrated"
  }' \
  --model gemini-3-pro-image-preview --thinking 16384

Face & Identity Swaps

Transfer faces between images with four approaches:

python3 .claude/skills/gemini/scripts/generate_image.py \
  '{
    "task": "Place face from Image 2 onto body in Image 1",
    "from_image_1": {"keep": ["body", "pose", "clothing", "scene"]},
    "from_image_2": {"extract": ["face", "expression", "skin tone"]},
    "integration": {"neck_blend": "seamless", "lighting": "match Image 1"}
  }' \
  --image body_template.png --image face_source.png \
  --model gemini-3-pro-image-preview

For detailed techniques, failure fixes, and source image selection, see examples/advanced-techniques.md#face--identity-swaps.

See examples/advanced-techniques.md for detailed guides on all techniques.

Anti-Patterns to Avoid

1. Generating without approval - Unless user triggers Bypass Mode, always show structured breakdown and get explicit "yes"
2. Skipping clarifying questions - ALWAYS ask questions, even if the request seems clear (unless bypassed)
3. Inventing model names - Use ONLY gemini-2.5-flash-image or gemini-3-pro-image-preview
4. Ignoring conversation context - Always check for recent generations to enable editing
5. Not iterating - Always ask "Would you like any changes?" after generation
6. Wrong model for task - Use flash for iterations, pro for final quality
7. Wrong aspect ratio - Match ratio to intended use case
8. Ignoring rate limits - Be aware of free tier quotas (~100/day flash, ~10/day pro)
9. Ambiguous image roles - For multi-image operations, always confirm which image serves which role

Error Handling

Examples

See examples/prompts.md for prompt inspiration.

Updating This Skill

When asked to update Nano Banana / Gemini capabilities:

1. Fetch Current Documentation

Check these sources for updates:

• Image Generation: https://ai.google.dev/gemini-api/docs/image-generation
• Models List: https://ai.google.dev/gemini-api/docs/models/gemini
• Rate Limits: https://ai.google.dev/gemini-api/docs/rate-limits

2. Compare and Update

Check for changes in:

• Model names/IDs
• Rate limits and quotas
• New parameters or capabilities
• API endpoint changes

3. Update Files

4. Verify

After updating, run a test generation to confirm the changes work:

python3 .claude/skills/gemini/scripts/generate_image.py "test image" --model [new-model-name]

File Reference