nanobanana-skill

# Nanobanana Image Skill

Use the bundled `nanobanana.py` tool to generate or edit images with Gemini image models. The default path now targets **Nano Banana 2** (`gemini-3.1-flash-image-preview`) and turns on **thinking summaries** plus **Google Search grounding** by default, because those defaults are the main reason to use this skill instead of a generic image prompt.

## When to use this skill

Use it for:

1. Creating a new image from text
2. Editing or remixing one or more existing images
3. Combining several reference images into one composition
4. Requests where factual freshness matters and image grounding should use live web data
5. Requests that need strong text rendering, layout reasoning, or more deliberate composition

Do not use it for:

1. Non-image tasks
2. Image work that explicitly must use another provider or another installed image skill

## Requirements

1. `GEMINI_API_KEY` must exist in `~/.nanobanana.env` or the shell environment.
2. Python dependencies from `requirements.txt` must be installed.
3. The executable is the `nanobanana.py` file in this same skill directory. Resolve its absolute path once before running it.

Example env file:

```bash
GEMINI_API_KEY=sk-dummy
```

## Default behavior

Unless the user explicitly asks otherwise, prefer these defaults:

1. Model: `gemini-3.1-flash-image-preview`
2. Search grounding: enabled
3. Thinking summaries: enabled
4. Thinking level: `high`
5. Resolution: `1K`
6. Aspect ratio: leave unspecified unless the user clearly wants a shape

Leaving aspect ratio unspecified is usually better for edits because Gemini can match the input image shape. For text-only generation, pick an aspect ratio only when the user implies a format such as poster, square post, banner, phone wallpaper, or ultrawide hero image.

## Workflow

### 1. Clarify only the missing constraints

Ask only for details that materially affect the result:

1. The image brief or editing instruction
2. Any input/reference images to use
3. Target format or aspect ratio if implied by the use case
4. Output filename if the user cares where it lands

Do not force the user to choose a model, search mode, or thinking mode unless they asked for that level of control. The latest Nanobanana 2 path is already the default.

### 2. Choose the right mode

Use **generate** when there are no input images.

Use **edit/composite** when there are one or more input images. Nanobanana 2 can mix multiple references, so do not artificially limit the task to a single image if the user is clearly asking for a blend, lineup, storyboard, or consistency pass.

### 3. Run the bundled tool

Use the script beside this skill file.

Basic generation:

```bash
python3 /absolute/path/to/nanobanana.py \
  --prompt "Create a high-end coffee bag package design with tactile paper texture and clear typography" \
  --output /absolute/path/to/output/package.png
```

Editing or compositing:

```bash
python3 /absolute/path/to/nanobanana.py \
  --prompt "Turn these product photos into a clean 4:5 ecommerce hero image with a soft studio shadow and subtle headline area" \
  --input /absolute/path/to/ref1.png /absolute/path/to/ref2.png \
  --aspect-ratio 4:5 \
  --output /absolute/path/to/output/hero.png
```

Grounded generation with saved text metadata:

```bash
python3 /absolute/path/to/nanobanana.py \
  --prompt "Use Google Search to ground an editorial illustration about the most recent lunar mission and create a clean magazine cover concept" \
  --aspect-ratio 2:3 \
  --text-output /absolute/path/to/output/cover.txt \
  --metadata-output /absolute/path/to/output/cover.json \
  --output /absolute/path/to/output/cover.png
```

### 4. Return the result clearly

Always tell the user:

1. The saved image path or paths
2. Whether search grounding stayed enabled
3. Whether text/thought summaries were saved anywhere
4. Any relevant limitation or warning from the run

If the model returns text but no image, report that plainly and suggest a more explicit image-focused prompt instead of pretending the run succeeded.

## Recommended options

### Models

1. `gemini-3.1-flash-image-preview`: default. Best default for fast, high-volume image generation and editing with Nanobanana 2 features.
2. `gemini-3-pro-image-preview`: slower, but a good override for very detail-heavy or typography-sensitive work.
3. `gemini-2.5-flash-image`: legacy fallback if the user specifically wants the older Nanobanana model.

### Aspect ratios

Supported ratios:

1. `1:1`
2. `1:4`
3. `1:8`
4. `2:3`
5. `3:2`
6. `3:4`
7. `4:1`
8. `4:3`
9. `4:5`
10. `5:4`
11. `8:1`
12. `9:16`
13. `16:9`
14. `21:9`

Quick picks:

1. `1:1` for logos, icons, thumbnails, and general social posts
2. `4:5` for feed posts and product cards
3. `2:3` for posters and book-cover style work
4. `9:16` for stories, shorts, and phone wallpaper
5. `16:9` or `21:9` for slides, banners, and desktop hero art
6. `1:4`, `4:1`, `1:8`, `8:1` for very tall or very wide experimental layouts now supported by Nanobanana 2

### Resolution

1. `512px`: Nanobanana 2 only. Best for quick ideation.
2. `1K`: default. Good tradeoff for most requests.
3. `2K`: use for polished deliverables.
4. `4K`: use when the user explicitly needs a high-resolution final.

### Thinking and search

1. Keep search grounding on by default when the request could benefit from live facts, current events, or real product references.
2. Keep thinking summaries on by default because Nanobanana 2 often composes better on multi-constraint tasks.
3. Lower `--thinking-level` to `low` or `minimal` when the user prioritizes latency over refinement.
4. Disable search only when the user wants a purely imaginative result or explicitly requests no web grounding.

## Prompting guidance

Good Nanobanana prompts are direct production briefs, not vague art wishes. Include:

1. Subject
2. Visual style
3. Composition or camera framing
4. Required text if any
5. Output use case
6. Constraints such as brand colors, empty space, or