/oma-image

name: oma-image
description: Generate raster images or reference-guided variations through the
  OMA image CLI. Use for image assets or explicit vendor comparisons; pixel
  editing uses an editor.

Image Agent - Multi-Vendor Image Router

Scheduling

Goal

Generate images and visual assets through authenticated multi-vendor routing while preserving prompt clarity, reference-guided regeneration, 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 for a new generated variation 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)
• Regenerating a new image that follows a supplied reference's subject, style, lighting, or composition

When NOT to use

• Pixel-level editing, masking, inpainting, object removal, compositing, cropping, resizing, or format conversion -> out of scope; use an image editor or a tool that explicitly supports that operation.
• 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 the `image:` section of `.agents/oma-config.yaml`

Control-flow features

• Branches by prompt ambiguity, vendor auth, cost threshold, reference-guided regeneration 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. Classify a supplied image as a reference for a newly generated variation, or as a request for unsupported pixel/mask editing. 3. Check authentication, cost guardrails, output path, and count limits.

Transitions

• If the subject or intended result cannot be inferred, clarify that missing input; otherwise proceed with reasonable defaults.
• If `--vendor all` is requested, require every requested vendor to be available.
• If the request is reference-guided regeneration and the selected vendor supports references, pass it automatically.
• If the request requires pixel, mask, crop, resize, or format editing, stop before generation and name the unsupported operation and an appropriate editor route.
• 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

Tools and instruments

• `oma image generate`, `oma image doctor`, `oma image vendor list`
• 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 --output json

With reference images:

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

Resource scope

| Scope | Resource target | |-------|-----------------| | `LOCAL_FS` | Reference images, generated images, manifests | | `PROCESS` | Provider CLIs and image router commands | | `NETWORK` | Pollinations/Gemini or provider APIs | | `CREDENTIALS` | Provider auth and API keys |

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. **Resolve the brief**: use supplied details and reasonable creative defaults. Ask only when a missing choice materially changes the requested result. Do not require approval of an expanded prompt when generation is already authorized. 2. **Authentication-aware dispatch**: detect which vendor CLIs are available and run only those; with `--vendor all`, every requested vendor must be available (strict). Caveat: the `antigravity` health check verifies installation only (`agy --version`) — a signed-out agy passes health and fails at generate time with agy's own error. 3. **Cost guardrail**: confirm before executing runs whose estimated cost is ≥ `$0.20` (configurable). `--yes` / `OMA_IMAGE_YES=1` bypass. Choose generation from the requested outcome, not keyword presence. **Non-interactive contex