Oma Image

Image Agent - Multi-Vendor Image Router

Scheduling

Goal

Generate images and visual assets through authenticated multi-vendor routing while preserving prompt clarity, reference-image handling, cost controls, and reproducible output manifests.

Intent signature

• User asks to generate images, visual assets, illustrations, product photos, concept art, mockups, or AI art.
• Another skill needs shared image-generation infrastructure.
• User provides reference images or asks for vendor comparison.

When to use

• Generating images, visual assets, illustrations, product photos, concept art
• Comparing output between multiple image models for the same prompt
• Producing images from prompts within editor workflows (Claude Code, Codex, Gemini CLI)
• Other skills needing image generation infrastructure (shared invocation)

When NOT to use

• Editing an existing image or photo manipulation -> out of scope
• Generating videos or audio -> out of scope
• Inline vector art / SVG composition from structured data -> use a templating skill
• Simple asset resizing or format conversion -> use a dedicated image library

Expected inputs

• Image prompt or creative brief
• Optional vendor, size, quality, count, output directory, and reference images
• Authentication/environment state for Codex, Pollinations, or Gemini

Expected outputs

• Generated image files under .agents/results/images/ or requested output directory
• manifest.json with prompt, vendor, model, and reproducibility metadata
• Vendor comparison outputs when --vendor all is used

Dependencies

• oma image generate CLI and vendor authentication
• Codex image generation, Pollinations API, or Gemini API/CLI strategy
• resources/vendor-matrix.md, resources/prompt-tips.md, and config/image-config.yaml

Control-flow features

• Branches by prompt ambiguity, vendor auth, cost threshold, reference-image support, path safety, and safety/timeout exit codes
• Calls external vendor APIs/CLIs
• Reads reference images and writes generated images plus manifests

Structural Flow

Entry

1. Validate that the request contains enough subject, setting, style, usage, and aspect-ratio signal. 2. Detect attached/reference images and vendor support. 3. Check authentication, cost guardrails, output path, and count limits.

Scenes

1. PREPARE: Clarify or amplify prompt and choose vendor strategy. 2. ACQUIRE: Validate auth, references, output path, and provider availability. 3. ACT: Invoke oma image generate with selected vendor(s), prompt, references, and options. 4. VERIFY: Check manifest, output files, exit code, and provider result. 5. FINALIZE: Return output paths and relevant warnings.

Transitions

• If prompt lacks required signal, clarify or show amplified prompt before generation.
• If --vendor all is requested, require every requested vendor to be available.
• If reference path is supported by selected vendor, pass it automatically.
• If estimated cost exceeds guardrail, require confirmation unless bypassed.

Failure and recovery

• If auth is missing, report vendor-specific authentication requirement.
• If reference support is unavailable for the selected vendor, reject with actionable guidance.
• If local CLI is outdated, ask user to run oma update.
• If generation times out or is blocked, surface exit code and provider status.

Exit

• Success: images and manifest exist in the output directory.
• Partial success: some vendors fail in comparison mode and failures are reported.
• Failure: no image is produced and the route/cost/auth/safety blocker is explicit.

Logical Operations

Actions

Tools and instruments

• oma image generate, oma image doctor, oma image list-vendors
• Codex, Pollinations, and Gemini provider paths
• Prompt tips, vendor matrix, and image config

Canonical command path

oma image doctor
oma image generate "<prompt>" --vendor auto --size auto --quality auto --format json

With reference images:

oma image generate --reference "<absolute-path>" --vendor codex "<prompt>"

Resource scope

Preconditions

• Prompt is sufficiently specified or user approves amplification.
• Required vendor auth and output permissions exist.
• Reference paths are accessible when used.

Effects and side effects

• Creates image files and manifests.
• May call paid or rate-limited provider APIs.
• May read attached/reference images.

Guardrails

1. Clarify before invoking: if the user's request is ambiguous about subject, style, composition, or usage context, ask the user first or amplify the prompt explicitly (showing the user the expanded version for approval). Do NOT silently generate from a vague prompt. See Clarification Protocol below. 2. Authentication-aware dispatch: detect which vendor CLIs are authenticated and run only those; with --vendor all, every requested vendor must be available (strict). 3. Cost guardrail: confirm before executing runs whose estimated cost is ≥ $0.20 (configurable). --yes / OMA_IMAGE_YES=1 bypass. Default vendors pollinations (flux/zimage) and antigravity (nano-banana via Gemini Code Assist) are free, so auto-triggering on keywords is safe. 4. Path safety: output paths outside $PWD require --allow-external-out. 5. Cancellable: SIGINT/SIGTERM aborts in-flight provider calls and the orchestrator. 6. Deterministic outputs: every run writes manifest.json next to the images for reproducibility. 7. Max `n` = 5: wall-time bound. 8. Exit codes align with `oma search fetch` (0, 1, 2=safety, 3=not-found, 4=invalid-input, 5=auth-required, 6=timeout).

Clarification Protocol

Before invoking oma image generate, the calling agent runs this checklist against the user's request. If any answer is "no / unknown", clarify with the user first.

Required signal (must be present or inferable):

• [ ] Subject: what is the primary thing in the image? (object, person, scene)
• [ ] Setting / backdrop: where is it? (context, environment)

Strongly recommended (ask if absent AND not inferable from context):

• [ ] Style: photorealistic, illustration, 3D render, oil painting, concept art, flat vector, …?
• [ ] Mood / lighting: bright vs moody, warm vs cool, dramatic vs minimal
• [ ] Usage context: hero image, icon, thumbnail, product shot, poster? (dictates aspect ratio + composition)
• [ ] Aspect ratio / resolution: any WxH where each edge is a multiple of 16 between 16 and 3840 and aspect ∈ [1:3, 3:1] (e.g. 1024x1024 square, 2048x1152 16:9, 3840x2160 4K UHD, 1024x1536 portrait), or auto.

Amplification shortcut. For brief prompts (e.g. "a red apple"), do not pop clarifying questions if the request is genuinely that simple. Instead amplify inline and show the user the expanded version before invoking:

User: "a red apple"

Agent: "I'll generate this as: a single glossy red apple centered on a clean white background, soft studio lighting, photorealistic, shallow depth of field, 1024×1024. Shall I proceed, or would you like a different style/composition?"

Skip both clarification and amplification when the user has clearly authored a full creative brief (≥ 2 of: subject + style + lighting + composition). Respect their prompt verbatim.

Category-specific briefs (app mockup, poster, thumbnail, infographic, comic panel, avatar): consult resources/prompt-tips.md → External Prompt Libraries.

Output language. Generation prompts are sent to the provider in English (image models are trained predominantly on English captions). Translate the user's request if they wrote in another language, and show them the translated version during amplification so they can correct misreadings.

Vendors

This skill follows oh-my-agent's CLI-first concept: whenever a vendor's native CLI can drive generation (and return raw bytes), the subprocess path is preferred over direct API keys. Direct API is only used as a fallback for vendors whose CLI can't yet emit raw image bytes.

The direct Gemini path (gemini -p stream, generativelanguage.googleapis.com API) is deprecated. agy is the supported Gemini image route — it's free with Gemini Code Assist and doesn't require billing on AI Studio.

Invocation

Standalone

/oma-image a red apple on white background
/oma-image --vendor all --size 1536x1024 jeju coastline at sunset
/oma-image -n 3 --quality high --out ./hero "minimalist dashboard hero illustration"

Shell CLI

oma image generate "<prompt>" [--vendor auto|codex|pollinations|antigravity|all] [-n 1..5] \
                             [--size WxH|auto] \
                             [--quality low|medium|high|auto] \
                             [--out <dir>] [--allow-external-out] \
                             [-r <path>]... \
                             [--timeout 180] [-y] [--no-prompt-in-manifest] \
                             [--dry-run] [--format text|json]
oma image doctor
oma image list-vendors

Reference Images (-r, --reference)

Attach up to 10 reference images (PNG/JPEG/GIF/WebP, ≤ 5MB each) to guide style, subject identity, or composition. Repeatable or comma-separated.

oma image generate -r ~/Downloads/otter.jpeg "same otter in dramatic lighting"
oma image generate -r a.png -r b.png "blend these two styles"

Supported vendors:

Paths: absolute or relative to $CWD. Host CLIs usually expose attached images via:

• Claude Code: ~/.claude/image-cache/<session>/N.png (surfaced in system messages as [Image: source: <path>])
• Antigravity: workspace upload directory (exact path shown in IDE)
• Codex CLI as host: user must pass the filesystem path explicitly; in-conversation attachments are not forwarded

Agent Behavior: Auto-forward Attached References (MANDATORY)

When ALL of the following are true, the calling agent MUST pass the attached image via --reference <path> automatically. Never describe the image in prose as a workaround.

1. The user asks to generate or edit an image (referencing the attached one by phrases like "이거", "this image", "same style as this", "이 수달", etc.). 2. A host-surfaced attached image is visible to the agent (e.g. a Claude Code system message with [Image: source: <path>], or an Antigravity workspace upload path, or an explicit filesystem path in the user's message). 3. The selected vendor supports references (codex or antigravity).

Required action: invoke oma image generate --reference <absolute-path> --vendor <codex|antigravity> "<prompt>". If the user didn't specify a vendor, default to codex (CLI-first, widest availability). Do NOT:

• Fall back to prose description ("I'll describe the otter's appearance...").
• Ask the user to re-type or re-attach the path.
• Claim the CLI doesn't support references without first running oma image generate --help to verify.

If the local CLI is outdated (--reference is missing from --help): tell the user to run oma update once, then retry. Do not silently degrade to prose.

If the reference path is from Claude Code's `image-cache`: note to the user that the path is session-scoped and suggest copying the file to a durable location if they want to reuse it later. Still proceed with the generation.

Shared Infrastructure (from other skills)

Other skills call oma image generate --format json and parse the JSON manifest from stdout.

Output Layout

.agents/results/images/
├── 20260424-143052-ab12cd/                    # single-vendor run
│   └── pollinations-flux.jpg
│       (or codex-gpt-image-2.png)
│       manifest.json
└── 20260424-143122-7z9kqw-compare/            # --vendor all run
    ├── codex-gpt-image-2.png
    ├── pollinations-flux.jpg
    └── manifest.json

References

Follow resources/execution-protocol.md step by step. See resources/vendor-matrix.md for strategy precheck rules. Use resources/prompt-tips.md for writing effective prompts. Before submitting, run resources/checklist.md.

Configuration

Project-specific settings: config/image-config.yaml. Env vars: OMA_IMAGE_DEFAULT_VENDOR, OMA_IMAGE_DEFAULT_OUT, OMA_IMAGE_YES, POLLINATIONS_API_KEY.

• Execution steps: resources/execution-protocol.md
• Vendor matrix: resources/vendor-matrix.md
• Prompt tips: resources/prompt-tips.md
• Checklist: resources/checklist.md
• Context loading: ../_shared/core/context-loading.md

Checklist: before you run oma image generate

• [ ] Prompt is specific about scene, subject, and style (see prompt-tips.md).
• [ ] --vendor matches available authenticated CLIs. Run oma image doctor if unsure.
• [ ] -n is ≤ 5; wall time scales with count.
• [ ] --out is inside the project, or you've set --allow-external-out.
• [ ] Estimated cost is acceptable. Run --dry-run first for unfamiliar combinations.
• [ ] Secrets are not in the prompt, or --no-prompt-in-manifest is set.
• [ ] For --vendor all, every enabled vendor is healthy (strict mode exits 5 otherwise).

Checklist: after the run

• [ ] manifest.json was written inside the run folder.
• [ ] Each recorded run has an ok status or a classified error.
• [ ] Strategy attempts are objects (not compact strings).
• [ ] Images open without corruption.
• [ ] If results are consumed downstream, the consumer parses --format json stdout rather than re-reading the manifest file.

Image Agent - Execution Protocol

Step -1: Clarify / Amplify Prompt (agent-side, before oma image generate)

Run the Clarification Protocol in SKILL.md before shelling out.

Step 0: Parse Request

1. Extract prompt and flags from the invocation. 2. Resolve defaults from config/image-config.yaml → env vars → CLI flags (lowest to highest precedence). 3. Validate:

• count ∈ [1, 5]
• size is auto or any WxH passing size-guard.ts (each edge ∈ [16, 3840], multiples of 16, aspect ratio 1:3..3:1).
• quality ∈ {low, medium, high, auto}
• vendor ∈ {auto, codex, pollinations, antigravity, all} or a concrete registered name.
• reference (if any): each path exists, is a regular file ≤ 5MB, magic-byte-matches PNG/JPEG/GIF/WebP, ≤ 10 total, and duplicate paths are rejected with exit 4.

4. If invalid: exit code 4 and a message identifying the offending field.

Step 0.5: Reference Image Handling

When --reference <path...> is supplied:

1. Validate every path via reference-guard.ts. On failure → exit 4. 2. Reject the request if the selected vendor(s) do not support references (currently only codex and antigravity). Pollinations returns exit 4 with a hint to switch vendor. 3. Pass validated absolute paths through GenerateInput.referenceImages:

• codex provider appends -i <path> per reference to codex exec and adds a guidance sentence to the instruction text.
• antigravity provider copies each reference into a per-run temp dir, exposes it to agy via --add-dir <tmpdir>, and lists the resulting paths inline in the agy prompt.

4. Record reference paths in manifest.json under reference_images (top-level array of absolute paths).

Auto-forward attached images (MANDATORY)

If the user asks to generate/edit an image AND a host-attached image is visible to the agent (e.g. [Image: source: <path>] in a Claude Code system message, Antigravity workspace upload, or explicit user-provided path), the agent MUST pass it via --reference <path>. Do not fall back to describing the image in prose. Do not ask the user to re-type the path. If oma image generate --help shows no --reference flag, instruct the user to run oma update and retry; do not silently degrade.

Host-Specific Reference Paths

Agents invoking oma image generate --reference should surface the following host-specific locations to the user:

Agents should prefer user-supplied explicit paths (e.g., ~/Downloads/otter.jpeg) over host-cache paths when durability across sessions matters.

Step 1: Vendor Selection

1. Call health() on every registered provider in parallel. 2. Classify:

• healthy: ok: true
• unhealthy: ok: false with a hint

3. Decide based on --vendor:

• auto: continue with every healthy provider. If zero → exit 5.
• all: every provider must be healthy. Any missing → exit 5 naming the specific vendor.
• <name>: resolve the named provider. If unhealthy → exit 5 with its hint.

4. Log using: <vendor(s)> to stderr before generation.

Step 2: Cost Guardrail

1. Estimate cost as sum(per_image_usd[vendor][model][quality] × count) over all selected vendors. 2. If --dry-run: print the plan (vendors, counts, outDir, cost) and exit 0. 3. If estimate ≥ cost_guardrail.estimate_threshold_usd and not --yes/OMA_IMAGE_YES=1:

• Prompt user on stderr: Estimated cost $X.XX. Proceed? (y/N)
• Decline → exit 1.

Step 3: Cancellation Setup

1. Install SIGINT/SIGTERM handlers that call AbortController.abort(). 2. Thread the signal into every provider call via GenerateInput.signal.

Step 4: Dispatch

• Single vendor: run provider.generate(input) sequentially.
• Multi-vendor (`all` or `auto` with 2+ healthy): Promise.allSettled across providers.
• Providers with sub-strategies escalate internally and record every strategy attempt (ok/skipped/failed with reason).
• Non-retryable errors (safety-refused, invalid-input) short-circuit the escalation chain.

Step 5: Write Artifacts

1. Save each image to outDir/<vendor>-<model>[-<n>].png. 2. Build manifest.json with schema version 1 (see vendor-matrix.md for fields). 3. If --no-prompt-in-manifest is set, replace prompt with prompt_sha256.

Step 6: Report

1. For each run, print a one-line status to stderr:

• [oma image] <vendor> ok (Xs) -> <file>
• [oma image] <vendor> failed (<kind>): <reason>

2. Print manifest path. 3. For --format json: write {exitCode, manifestPath, runs} to stdout as one JSON object.

Step 7: Exit Code Aggregation

• Any successful run in parallel mode → exit 0 (failures still in manifest).
• All failures → pick the most specific exit code:
• safety-refused → 2
• invalid-input → 4
• auth-required / not-installed → 5
• timeout → 6
• otherwise → 1

On Error

Prompt Tips

Good prompts are specific about scene, subject, lighting, and style. Both gpt-image-2 (codex) and gemini-2.5-flash-image (antigravity / nano-banana) respond well to the same structural cues.

Structure

Scene/backdrop → Subject → Details → Constraints

Example: minimalist product photography: single white ceramic coffee cup on dark marble surface, steam rising softly, dramatic side lighting

Do's

• Lighting: "warm golden hour side light", "overcast diffused", "backlit with rim light"
• Camera: "shallow depth of field", "aerial view", "close-up macro", "35mm film grain"
• Style: "photorealistic", "oil painting", "3D render", "concept art", "isometric vector"
• Mood: "serene", "dramatic", "moody", "vibrant", "washed-out"
• Resolution cue: "ultra detailed", "8K", "high fidelity"

Don'ts

• Avoid vague prompts like "a nice picture"; both models produce generic output.
• Don't stack contradicting styles ("photorealistic cel-shaded 3D").
• Skip negative prompts; neither gpt-image-2 nor gemini-2.5-flash-image treats them as first-class.

Examples

Vendor Nuances

• Codex (`gpt-image-2`): prefers slightly longer, descriptive prompts. Quality flag high noticeably sharpens fine detail but doubles generation time.
• Antigravity (`gemini-2.5-flash-image` aka nano-banana): robust on CJK-composed scenes ("hanok", "cherry blossom"); slightly stronger on illustrated/painterly styles. Driven via the agy CLI's agentic loop — output is JPEG by default even if .png is requested (the provider sniffs magic bytes and renames the extension accordingly).

Comparing Output

--vendor all generates the same prompt on both providers and writes both PNGs into a …-compare/ folder with a single manifest.json. Use it for A/B picking when starting a new visual style.

External Prompt Libraries (agent reference only)

When the Clarification Protocol (see SKILL.md) reaches the amplify step, these galleries provide structural references.

For pollinations (flux / zimage), patterns from either library transfer; use the subject framing, lighting cues, and style-keyword structure, not the literal wording.

How to use (agent-side):

1. Classify the user's intent into one of the 7 categories. If no match, fall back to the Scene/backdrop → Subject → Details → Constraints template at the top of this file. 2. Fetch the relevant README section via gh api, e.g. Korean user + nano-banana:

   gh api repos/YouMind-OpenLab/awesome-nano-banana-pro-prompts/contents/README_ko-KR.md \
     --jq .content | base64 -d | less

Scan headings like ### No. N: <Category> - <Title> to locate 1–2 analogous entries. 3. Internalize the pattern, do not reproduce the text. Extract lighting / framing / camera / style-keyword choices. The structural approach is not copyrightable; the expression is. 4. Compose your amplified prompt by applying that pattern to the user's subject in your own wording. Show the result to the user for approval before invoking oma image generate.

Fallback: If no category matches, use the structural template at the top of this file.

Vendor Matrix

Reference Image Support (--reference / -r)

All paths are validated in reference-guard.ts (magic-byte MIME check + size + count + duplicate rejection) before dispatch. The magic-byte-detected MIME is threaded through GenerateInput.referenceImages and used verbatim at the vendor API boundary; file extension is never trusted for MIME type.

Codex

Codex requires --skip-git-repo-check for invocation inside a git worktree; this is inherited from the upstream codex-image skill and is a known dependency of the Codex CLI image path.

Antigravity

The Antigravity CLI (agy) is an agentic CLI that runs against the user's Gemini Code Assist subscription (no separate API key, no per-image charge). It exposes an internal image generation tool that drives Gemini-family image models — including the one currently called "nano-banana" — but does not expose a model selector to callers. We deliberately do not pretend to choose: the prompt has no model hint, the manifest records "model": "agy-internal", and the output filename is antigravity-<runShortid>.<ext> with no model segment.

Why agy instead of the Gemini CLI / direct API

• gemini -p runs the full agent loop and does not emit raw inlineData bytes on stdout (as of Gemini CLI 0.38) — it tries to invoke image-generation tools itself, often recursing back into oma-image.
• The direct generativelanguage.googleapis.com API requires GEMINI_API_KEY plus billing on AI Studio. Image models are not in the free tier.
• agy -p already wraps Gemini Code Assist credentials in the user's Antigravity session and exposes a working image_gen tool. It writes raw bytes to disk for us, so we don't have to capture them from stdout.

Output format gotcha

Gemini image surfaces currently return JPEG bytes regardless of the requested filename extension. The provider writes to a .img placeholder, sniffs the actual format from the first 12 bytes, then renames to .png / .jpg / .webp / .gif. The result's mime field reflects the sniffed format, not the user's requested extension.

Strategy Attempt Record

Manifest field strategy_attempts is always an array of objects:

{ "strategy": "codex-exec-oauth" | "agy-print" | "pollinations-http",
  "status": "ok" | "skipped" | "failed",
  "reason"?: string,
  "duration_ms"?: number }

The last successful strategy also appears on the run as strategy.

Error Classification