Generate

/generate

Calls Google's Gemini media models directly through the Gemini API — no third-party routing layer. One key, one bill, and access to the newest Google-specific features (Nano Banana Pro's multi-image fusion, Omni Flash's synced audio) as soon as they ship.

How a generation flows

1. Route — pick the model for the job (draft image, standard image, quality image, or video) and read its recipe file before calling anything. Recipes hold the exact request shape and any quirks that have shown up since the model shipped.
2. Load references — pull any real reference images (logos, faces, style shots) from generations/refs/, or from a named reference set if the request invokes /generate frf or says "from reference" or "on brand" (see Reference library). Never substitute a text description for a reference image that exists.
3. Generate — call the API per the recipe, through the Interactions API (client.interactions.create) — the current, documented entry point for every model below. Images reply synchronously; video is a submit-then-poll operation for large outputs. Save the result flat into the generations folder.
4. Log — verify the generated file is actually on disk and non-empty, then write the sidecar JSON next to it (see Logging). Never log a generation whose file isn't there.

Models

gemini-3-pro-image-preview was deprecated 2026-05-28 and shut down 2026-06-25 — gemini-3-pro-image is its GA replacement. Model IDs move on Google's schedule, not this skill's; always read the recipe file rather than trusting this table from memory.

Rough costs, Standard (sync) tier as of August 2026 — re-check https://ai.google.dev/gemini-api/docs/pricing before quoting, these move:

Every row above is billable — image generation is not free just because it's cheap. Quote current pricing and get explicit approval before any of them, not only video (see Rules).

Reference library

Loose files in generations/refs/ (workspace-relative, like all output — see Output) work as always. On top of that, a folder one level down is a named reference set — the images for one brand, product, or recurring character, grouped so the user can pull them all in with one phrase.

A user registers a folder in one of two ways:

• Import (copy) — "import ~/company/brand-assets as brand": copy the image files into generations/refs/brand/. A snapshot — it survives the original folder being moved or edited.
• Link (live) — "link ~/company/brand-assets as brand": don't copy anything; record the path in generations/refs/sets.json. The folder is read fresh at generation time, so new assets show up without re-importing.

sets.json maps set names to linked folders:

{
  "brand": {
    "path": "~/company/brand-assets",
    "output": "public/images",
    "linked": "2026-08-01T10:00:00Z",
    "notes": "logo_dark.png is the primary mark; palette.png shows brand colors"
  }
}

output is optional — see "Where the output lands" below. Imported sets can carry the same settings in a set.json inside their folder.

If the user doesn't name the set, default to the folder's own name. To resolve a set name at generation time, check generations/refs/<name>/ first, then sets.json. If a linked path no longer exists, stop and ask — same rule as any missing reference, never approximate. After registering a set, list back the images found so the user can confirm the right folder came in.

Bootstrap — the set doesn't exist yet. When a ref-based request names a set that isn't there (including the very first "on brand"), create the folder (generations/refs/<name>/), tell the user its full path and that images dropped there will be used as references from now on, and stop. Never generate from an empty set — "on brand" with zero real brand pixels is exactly the text-description approximation the Rules forbid. Once the folder has at least one image, generation proceeds normally.

Generating from a set

• /generate frf <set> … — use that set's images as the reference inputs for the generation. The spoken form "generate from reference <set> …" works the same, and a raw folder path in place of a set name is fine too — treat it as a one-off set. Always prefixed with /generate — a skill registers exactly one slash command, taken from the name of the folder it's installed into (generate, not this file's name: frontmatter — see Supported Environments & Agents), so a bare /frf is rejected as an unknown command on agents like Claude Code that route slash commands strictly.
• "generate on brand …" — shorthand for /generate frf brand. If no set named brand exists yet, ask the user for a folder to link or import before generating anything.

Where the output lands. By default, ref-based generations save flat into the workspace's generations/ folder like everything else. A set can override that with an output folder — set it in sets.json, or just say "save these to public/images" — and then the generated file and its sidecar land there instead, ready to use in the project. Outputs never save into the refs folder itself: references in, results out, the two never mix.

Don't dump the whole folder into every call. Pick the images relevant to the job — the logo for a logo placement, style shots for a look, the product photos for that product — up to the model's reference limit: 1-2 on Nano Banana 2 Lite, a handful on Nano Banana 2, up to 14 on Nano Banana Pro. If the set holds more relevant images than a Lite draft can take, use the strongest 1-2 for drafting and the fuller set on the final rerun. Always tell the user which files went into the call; the sidecar log records them regardless.

Determinism & coherence

Two different jobs hide under "make it again": re-running one image, and keeping a family of images looking related. Neither the image models nor Gemini Omni Flash document a seed parameter on the Interactions API — there is no reproducibility contract to lean on, and no sidecar field promises one. Don't tell a user a rerun will reproduce a prior result; be straight that every call is non-deterministic, and lean on the levers below instead.

Iterate by delta. For "same image but change X": read the original's sidecar, reuse its exact prompt and reference images, and edit only the words that describe X. Hold model, image_size, and aspect_ratio fixed too — changing any of them re-rolls the composition. Never reconstruct the prompt from memory when the sidecar holds the exact original — that's the whole reason it's logged.

Chain edits statefully instead of re-rolling. The Interactions API supports previous_interaction_id for turning one interaction into an edit of the last, rather than a fresh generation — documented for Gemini Omni Flash (see its recipe for the exact shape); re-verify against the current docs before assuming the same holds for the image models. Log the response id in every sidecar so a later edit can chain onto it.

Promoting a draft doesn't carry anything forward automatically. Promoting a picked Lite draft to Nano Banana 2 or Pro re-rolls the composition from the prompt alone. The coherence lever there is the draft itself: pass the picked draft image as a reference alongside the original prompt, so the final is anchored to approved pixels rather than to a fresh roll of the same words.

Style anchors for sets. A reference set may carry a style.md — in generations/refs/<name>/ for imported sets, in the linked folder for linked sets — holding a short, fixed description of the set's look: palette, lighting, camera, rendering style. When present, prepend its contents to the prompt verbatim on every generation from that set. Don't paraphrase it; the whole point is that the same words hit the model every time. The sidecar's prompt field records the full assembled prompt, style block included. (style.md is a text anchor, never a reference image — don't try to send it as one.)

Series lock. For a run of images that must match each other — a character across scenes, a product line, episode covers — generate the first, get the user's approval on it, then pass that approved image as a reference into every subsequent call, on top of the set's refs and style block. Character-consistency series belong on Nano Banana Pro.

Supported Environments & Agents

This skill works across multiple AI agents and CLI tools:

• Antigravity: Supports direct Python API execution with GEMINI_API_KEY or native generate_image tool fallback for instant zero-key image previews.
• Antigravity CLI: Invoke via the agy binary (e.g. agy generate). Migrating from the retired Gemini CLI? Import your existing config/extensions with agy plugin import gemini.
• Claude Code: Skills load from ~/.claude/skills/<name>/ (global) or .claude/skills/<name>/ (project-local, checked in every parent directory up to the repo root) — never from .agents/skills, which is a different tool's path even though Claude Code's skill format follows the same open standard. The slash command Claude Code registers is the install folder's name, not this file's name: frontmatter (which is only a display label) — that's why both the install steps below and the skills CLI name the folder generate; renaming it renames the command too. Sub-commands like frf or update aren't separately registered, so always type them as arguments to /generate (/generate frf <set> …, /generate update) or as plain language; a bare /frf returns "Unknown command." Editing or adding skills inside an already-loaded skills/ directory takes effect immediately, mid-session — a restart is only needed the first time that top-level skills/ directory itself is created.
• Cursor, Codex, OpenCode: Compatible with any agent reading standard SKILL.md definitions in their own skills directory convention.

Installation

Install using the skills CLI:

npx skills add AntonioCardenas/generate-nanobanana

Or manually clone into your agent's skills directory:

git clone https://github.com/AntonioCardenas/generate-nanobanana ~/.claude/skills/generate

Updating

"/generate update" — or any ask to update this skill — refreshes the installed copy in place:

1. Find the install — the folder this SKILL.md was loaded from.
2. Refresh it — if the folder is a git clone (has .git), run git pull inside it. Otherwise re-run npx skills add AntonioCardenas/generate-nanobanana, which re-resolves to the latest and overwrites the install; if that's unavailable, clone the repo to a temp folder and copy SKILL.md, models/, and the READMEs over the installed files.
3. Report what changed — summarize the recent commit titles or the diff of SKILL.md and models/, so the user knows what they just got.
4. Restart to load it — the running session keeps the old version; tell the user to restart, same as after a fresh install.

An update touches only the skill's own files. Never touch the workspace's generations/ folder, reference sets, or sets.json — that's the user's data, not the skill's.

Authentication

Calls use a Google AI Studio key in the GEMINI_API_KEY environment variable. Check for it in this order:

1. Already exported — if the shell environment already has GEMINI_API_KEY, use it as-is.
2. A .env file at the workspace root — not the skill's own install folder, the root of the project being generated into. If the user has already set one up (GEMINI_API_KEY=... in it) and it's not yet exported, load it before the Python call — e.g. set -a; source .env; set +a — so the google-genai SDK's genai.Client() can pick it up from the environment.
3. Neither exists — stop and ask the user to set it up themselves: either export GEMINI_API_KEY=your_key_here (add it to their shell profile to survive new sessions), or a .env file at the workspace root with GEMINI_API_KEY=your_key_here. Setting up the key — including any .env file, .env.example template, or .gitignore entry — is the user's own responsibility; this skill only ever reads GEMINI_API_KEY once it's there, and never creates or edits those files itself.

• In Antigravity: If GEMINI_API_KEY is not present, you can seamlessly fall back to Antigravity's built-in generate_image tool for instant generation.

The recipes in models/ call the google-genai Python SDK directly. In agents that run this through a shell rather than a native Python tool (Claude Code, Codex, OpenCode, Cursor), check it's importable before the first call (python3 -c "import google.genai"). If it's missing, tell the user you're about to install Google's official google-genai package from PyPI, then run pip install google-genai — never silently, and never any other package on this skill's own initiative.

Output

• Save every file flat into the workspace's generations/ folder — at the root of the project the session is working in, created on first use — no subfolders. The user's images live next to the code that needs them, not off in the home directory. Reference images live in generations/refs/, where set folders one level down (and sets.json) are the only structure allowed.
• No workspace to root in (a session running loose outside any project)? Fall back to ~/generations so files still have one predictable home.
• Exception: a reference set with an output folder configured saves its generations — sidecars included — to that folder instead (e.g. straight into a project's public/images/). Never into the refs folder.
• Naming: {project}_{description}_{timestamp}.{ext}
• One flat folder means any future tool — a gallery page, a script, a plain search — can read the whole library with zero setup. Keep it that way rather than organizing into subfolders later. The flat rule is for outputs; the refs library is the one place with structure.

Rules

Quote cost and wait for explicit go-ahead before any paid generation — image or video. Every call in this skill spends real money against the user's Google AI Studio billing, not just video. A quote alone isn't approval, and one approval covers exactly one run. If a rerun is needed, quote and confirm again.

Draft on Nano Banana 2 Lite first; rerun the picked favorite on Nano Banana 2 or Pro. This mirrors how the models are priced — Lite for iteration, Nano Banana 2 for most finals, Pro only when the job needs its extras: heavy multi-image fusion, consistent characters across a series, or dense on-image text.

Never describe a face or logo in a text prompt — pass the real image as a reference instead. Descriptions of specific people or brand marks drift from the source almost every time. If the reference file is missing, stop and ask rather than approximating.

Don't promise reproducibility that no model here supports. No seed or determinism contract is documented on the Interactions API. When varying an existing image, start from its sidecar's exact prompt and references and change only the requested delta — see Determinism & coherence.

Run generations one at a time, not in parallel. Keeps rate limits and cost/approval tracking accurate — a batch of parallel video calls could blow past an approved budget before anyone notices.

Save, verify, then log — in that order. The generated file must be on disk and non-empty before the sidecar is written; the sidecar is the record that an image exists, so a sidecar without its image is a false log entry. If the API returned no image — only text, an error, a safety block — there is nothing to log: report the failure and the API's text to the user instead of writing anything.

Logging

After saving a generated file — and verifying it's on disk, per the Rules — write a matching .json sidecar with the same base filename next to it (e.g. hero_thumbnail_1774912000.json beside hero_thumbnail_1774912000.png). model is the exact model ID sent to the API (gemini-3.1-flash-lite-image), never the recipe's nickname (nano-banana-2-lite) — the sidecar is what makes a rerun possible, and a rerun needs the real ID:

{
  "model": "gemini-3.1-flash-lite-image",
  "prompt": "the exact prompt sent",
  "reference_images": ["generations/refs/brand/logo_dark.png"],
  "reference_set": "brand",
  "response_id": "v1_...",
  "params": { "aspect_ratio": "16:9", "image_size": "1K" },
  "cost": "$0.04",
  "created": "2026-07-31T14:20:00Z",
  "approved_by_user": true
}

response_id is what makes "same image but change X" and stateful edits (previous_interaction_id) possible weeks later — log it on every call, image or video. reference_set names the set the images came from — omit it when references were passed individually. For linked sets, list the resolved absolute paths in reference_images so the log stays accurate even if the link later changes.

This gives a full audit trail — what was generated, from what prompt, at what cost — without reconstructing it from memory weeks later.

Security

This is the skill's full capability footprint — never expand it on your own initiative:

• Network — HTTPS calls to Google's generativelanguage.googleapis.com only, per the recipes in models/. No other endpoint, ever.
• Secrets — GEMINI_API_KEY is only ever read (from the environment or a workspace .env the user already set up — see Authentication), never written. Never log it, print it, or put it in a sidecar, a prompt, or a committed file. This skill never creates or edits .env, .env.example, or .gitignore — that setup is the user's own responsibility.
• File writes — confined to the workspace: generations/ and generations/refs/ (including sets.json). Nothing outside the current project, and nothing related to key setup.
• Package installs — the official google-genai PyPI package, and only when it's missing (see Authentication). No other package, and never silently.

A skills marketplace's automated audit flagging this skill as medium risk is consistent with this list, not a sign of something hidden — a real API key, a real network call, and a conditional package install are exactly what a "call an external paid API" skill looks like to a scanner that can't see intent. If a change would add a new endpoint, a new install, or a write outside this list, treat that as a design decision for the user to approve, not something to do quietly.