| name | ccskill-nanobanana |
| description | Skill for image generation needs.
Generate and edit high-quality images via Google Nano Banana (Gemini Image API).
Two models: Nano Banana 2 Lite (fast, low-cost, default) and Nano Banana Pro
(high-resolution, dense text, complex instruction following).
Supports logos, infographics, illustrations, photorealistic images, and more.
|
ccskill-nanobanana — Nano Banana Image Generation Skill
Overview
This skill generates images with the Google Nano Banana family (Gemini Image API).
The user states their intent ("I want a hero image for my blog post"); Claude picks
the model, crafts a structured prompt, chooses parameters, and runs the command.
Users are not expected to write prompts themselves.
Sister skill: ccskill-gptimage (OpenAI gpt-image-2). If both are installed, see
"Sister skill comparison" below for which to reach for first.
Prerequisites
- The repository is installed via
./install.sh, which registers the
ccskill-nanobanana command in ~/.local/bin.
- If the command is not on PATH, fall back to the venv directly:
$CCSKILL_NANOBANANA_DIR/venv/bin/python $CCSKILL_NANOBANANA_DIR/generate_image.py "prompt"
- A Gemini API key must be configured (
GEMINI_API_KEY env var, or .env in the
repository root). Get one at https://aistudio.google.com/apikey
- If anything fails, run
ccskill-nanobanana doctor to diagnose.
Usage
ccskill-nanobanana generate "prompt" [options...]
Options
| Option | Description | Default | Choices |
|---|
--model | Model to use | lite | lite, pro, or any Gemini image model ID |
--resolution | Output resolution | lite: 1K / pro: 2K | 1K, 2K, 4K (lite supports 1K only) |
--aspect | Aspect ratio | 16:9 | 1:1, 16:9, 9:16, 4:3, 3:2, etc. |
--output | Output directory | ./generated_images | any path |
--reference | Reference image(s), repeatable | none | image file path (up to 14) |
Model Selection
| Nano Banana 2 Lite (lite) | Nano Banana Pro (pro) |
|---|
| Model ID | gemini-3.1-flash-lite-image | gemini-3-pro-image |
| Cost (approx.) | ~$0.034 / image (1K) | ~$0.134 (1K/2K) – $0.24 (4K) / image |
| Resolution | 1K only | 1K / 2K / 4K |
| Speed | Lightning fast | Slower ("thinking" model) |
| Best for | Everyday images, iteration, drafts, illustrations, photos | Dense text, complex infographics, 2K/4K output, strict multi-reference composition |
Default to lite. Switch to pro when the request needs:
- 2K/4K resolution output
- Long or dense legible text (infographics, posters with paragraphs)
- Complex multi-step instruction following or strict layout control
Examples
Basic generation (lite, 1K):
ccskill-nanobanana generate "a cat playing piano in watercolor style"
High-resolution wide image with Pro:
ccskill-nanobanana generate "sunset coastline, cinematic" --model pro --resolution 4K --aspect 16:9
Edit with reference images:
ccskill-nanobanana generate "change background to sunset" --reference ./original.png
ccskill-nanobanana generate "draw this person in this pose" --reference ./person.png --reference ./pose.png
Reference image use cases: partial editing (background, colors), style transfer,
character consistency, image compositing.
Prompting Guides (read before crafting prompts)
Pick the guide matching the selected model and Read it when crafting non-trivial prompts:
- Lite (default): guides/prompting-lite.md —
5 core components (Style/Subject/Setting/Action/Composition), editing
strategies, fast-iteration workflow.
- Pro: guides/prompting-pro.md — Creative
Director approach, text rendering & infographics, identity locking,
structural control, 2D→3D.
Universal principles (both models):
- Use natural language and full sentences, not keyword soups.
- Be specific: subject, setting, lighting, mood, materiality.
- When editing, state the change directly ("change the tie to green").
- For text in images, put the exact string in quotes and describe typography.
Output
- Images are saved to the output directory (default:
./generated_images),
filename is a timestamp (e.g., 20260702_153045.png); the extension is
auto-detected from the API response (PNG/JPEG/WebP).
- A JSON metadata sidecar
{image}.json is written next to each image,
recording model, prompt, resolution, aspect ratio, and reference images.
- Every image is also stocked into the user-wide gallery store
(
~/.ccskill-nanobanana/gallery/, override with CCSKILL_NANOBANANA_GALLERY_DIR),
regardless of which project it was generated from.
Browsing Generated Images
ccskill-nanobanana browse
ccskill-nanobanana browse --port 9000
ccskill-nanobanana browse --bind 0.0.0.0
browse has no built-in viewer. If ccskill-gallery
is installed, it launches that (a cross-skill viewer that also covers
ccskill-omniflash and ccskill-gptimage output); --port/--bind/--no-open
are passed through as-is. If it isn't installed, browse just prints where
the files live — the gallery store itself is always written to regardless.
Sister skill comparison (vs ccskill-gptimage)
| Use case | First choice |
|---|
| Fast, cheap everyday generation & iteration | nanobanana (lite) |
| Dense Japanese/multilingual text, complex instructions | gptimage or nanobanana (pro) — compare |
| 2K/4K high-resolution output | nanobanana (pro) |
| Transparent background | nanobanana (gptimage's gpt-image-2 cannot) |
| Reference-image fidelity with masks | gptimage (supports --mask) |
Notes
- Nano Banana is a paid API; charges apply per image. Prefer
lite unless the
task needs Pro (see Model Selection).
- Generated images include a SynthID watermark.
- Verify factual accuracy of generated diagrams/infographics before use.
Troubleshooting
Run ccskill-nanobanana doctor first. Common issues:
| Symptom | Fix |
|---|
command not found: ccskill-nanobanana | cd <repo> && ./install.sh, ensure ~/.local/bin is in PATH |
| API error mentioning key | Configure GEMINI_API_KEY (env or repo .env) |
モデル ... は解像度 ... に対応していません | lite is 1K-only; drop --resolution or use --model pro |
Old skill nano-banana-pro still appears | Re-run ./install.sh (it migrates the old registration) |
