image-nanobanana

Files (9)

• SKILL.md
• api.md · references/
• asset-recipes.md · references/
• gemini-cli.md · references/
• prompting.md · references/
• watermarks.md · references/
• nb-cli-setup.sh · scripts/
• nb-generate.py · scripts/
• nb-preflight.sh · scripts/

SKILL.md (first lines)

# Nano Banana Image Asset Generation

Produce professional, production-ready image assets — icons, banners,
thumbnails, OG cards, diagrams, patterns, character sets — with Google's
Gemini image models ("Nano Banana"). Two execution paths, one skill:

1. **Direct API** via `scripts/nb-generate.py` — the production path: exact
   aspect ratios, 512/1K/2K/4K sizes, editing with reference images, retries,
   JSON output, cost estimates.
2. **gemini-cli** + nanobanana extension — the interactive path for users who
   live in a gemini-cli session (`/generate`, `/edit`, `/icon`, ...).

Both paths produce images with **no visible watermark** (the Gemini "sparkle"
overlay exists only in the consumer Gemini app for free/Pro tiers). Every
image carries Google's invisible SynthID provenance mark — leave it intact.

## Facts that prevent broken work (June 2026)

| Fact | Consequence |
|---|---|
| GA model ids: `gemini-3.1-flash-image` (Nano Banana 2), `gemini-3-pro-image` (Nano Banana Pro) | Use these. The `-preview` ids **shut down 2026-06-25** |
| The nanobanana extension still defaults to a `-preview` id | Always pin `NANOBANANA_MODEL` (nb-cli-setup.sh does it) |
| Image models have **zero free-tier API quota** | A key without billing gets 429s — that's a billing problem, not a bug |
| gemini-cli consumer OAuth retires **2026-06-18** | API-key auth is the only durable gemini-cli setup |
| Visible sparkle watermark = consumer Gemini app (free/Pro) only | Never source production assets from the Gemini app; generate via API |

## Preflight (run once per session)

```bash
bash scripts/nb-preflight.sh          # human-readable; --quiet for JSON
```

It verifies python3/curl, finds the API key, probes the GA model with the key,
and audits gemini-cli/extension/auth. Exit codes: 0 ready, 2 usage, 4 missing
binary, 5 network, 6 key missing/rejected. One blind spot: preflight cannot
prove billing — an un-billed key still passes and then 429s on the first real
generation (that 429 means "enable billing", not "retry").

If there's no key: send the user to https://aistudio.google.com/apikey,
remind them to enable billing on the key's project, then **give them this
exact command to run in their own terminal** (it needs hidden keyboard
input, so the agent must not run it):

```bash
bash ~/.claude/skills/image-nanobanana/scripts/nb-cli-setup.sh --set-key -
```

It stores the key in `~/.gemini/.env` (chmod 600 — the one file gemini-cli,
the extension, and these scripts all read), live-validates it, and does
nothing else. **Never write a key into the skill folder** — it's a
git-tracked directory and keys placed there end up in commits. Don't attempt
generation before preflight passes — every failure mode after that is harder
to diagnose.

Which commands run where: the agent runs preflight and all generation
commands itself; the **user** runs `--set-key -` (hidden input) and the full
extension setup (Google shows interactive consent prompts) in their own
terminal.

## Generating assets

Default model choice: iterate on **flash** at 1K (cheap, fast), render the
final on the format the asset needs — switch to **pro** for maximum fidelity,
complex composition, or in-image text.

```bash
# Basic generation
python3 scripts/nb-generate.py "modern flat illustration of a rocket launch, purple gradient, no text" \
  -a 16:9 -s 1K

# Production render: pro model, 4K, named output
python3 scripts/nb-generate.py "minimalist app icon, bold checkmark, flat geometric, teal on off-white, no text" \
  -m pro -a 1:1 -s 4K -o assets/icons --name app-icon

# Variants to choose from
python3 scripts/nb-generate.py "..." -n 3

# Edit / iterate (pass the exact path the previous run printed — cheaper and
# more faithful than re-rolling)
python3 scripts/nb-generate.py "make the background darker, keep everything else identical" \
  -i assets/icons/app-icon-20260611-173000.png

# Pop the result straight into the user's image viewer
python3 scripts/nb-generate.py "..." --open

# Machine-readable result (paths, cost, model) on stdout
python3 scripts/nb-generate.py "..." --json

# Inspect the exact API payload without spending money or needing a key
python3 scripts/nb-generate.py "..." -a 21:9 -s 2K --dry-run
```

The script prints saved paths on stdout and a summary with clickable
`file://` links + cost on stderr.

**Always show the result, never just name a path.** After every generation:
in a runtime that can render images inline (Claude Code: use the Read tool on
the saved file), display the image to the user; otherwise pass `--open` to
pop the system viewer, or give the user the clickable `file://` link the
script printed. The user should see their image without hunting for it.

Model aliases: `-m flash` → gemini-3.1-flash-image · `-m pro` →
gemini-3-pro-image · `-m legacy` → gemini-2.5-flash-image. Aspect ratios:
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 everywhere; banner ratios
1:4, 4:1, 1:8, 8:1 on flash only. The script validates combinations before
spending money and prints an estimated cost after.

### Crafting the prompt

Write prompts as creative direction, not keyword soup. The four golden rules:
natural language, specific subjects/materials, state the purpose, edit instead
of re-rolling. For the full method (dimension checklist, camera/lighting
vocabulary, text rendering, anti-patterns, calibration examples), read
[references/prompting.md](references/prompting.md) before writing anything
beyond a trivial prompt. For named deliverables (icon, thumbnail, OG card...)
start from the matching recipe in
[references/asset-recipes.md](references/asset-recipes.md) — it fixes the
right model/aspect/size per asset type.

From kryptobaseddev/awesome-skills, MIT.

More from kryptobaseddev/awesome-skills