Ccskill Nanobanana

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

Model Selection

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            # delegates to ccskill-gallery if installed
ccskill-nanobanana browse --port 9000
ccskill-nanobanana browse --bind 0.0.0.0   # for remote-dev: view from another machine

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)

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: