oliverv/caro / .agents/skills/oma-image
oma-image
VerifiedGenerate raster images or reference-guided variations through the OMA image CLI. Use for image assets or explicit vendor comparisons; pixel editing uses an editor.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
| resources/checklist.md | markdown | 1.1 KB |
| resources/execution-protocol.md | markdown | 7.5 KB |
| resources/invocation.md | markdown | 6.8 KB |
| resources/prompt-tips.md | markdown | 4.6 KB |
| resources/vendor-matrix.md | markdown | 6.0 KB |
resources/execution-protocol.md
View on GitHub# 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 shipped code defaults → the `image:` section of `.agents/oma-config.yaml` → env vars → CLI flags (lowest to highest precedence). `config/image-config.yaml` is not consulted.
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.
- `model` (optional): vendor-specific override passed through as-is; applies to every vendor in the run set. `antigravity` ignores it.
- `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-guided regeneration
When `--reference <path...>` is supplied, the operation is reference-guided regeneration: it may
follow subject, style, lighting, or composition, but it cannot promise a pixel-preserving edit.
Before continuing, reject pixel/mask operations (inpainting, object removal, selective replacement,
crop, resize, or conversion) and route them to an editor or deterministic image processor.
1. Validate every path via `reference-guard.ts`. On failure → exit 4.
2. Vendor support check (only `codex` and `antigravity` support references):
- Explicit `--vendor <name>` / `--vendor all`: reject with exit 4 and a hint to switch vendor if any requested vendor lacks reference support.
- `--vendor auto`: silently drop reference-unsupported vendors from the healthy set. If no reference-supporting vendor remains: exit 4 when none is registered at all, exit 5 (with per-vendor setup hints) when some are registered but unhealthy.
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 for a reference-guided regeneration 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:
| Host CLI | Attachment Surface | Path pattern |
|----------|--------------------|--------------|
| **Claude Code** | `[Image: source: ...]` in system messages | `~/.claude/image-cache/<session-uuid>/<N>.png` (undocumented, verified empirically; cache is cleared on session end) |
| **Antigravity IDE** | Workspace upload via "Upload to Agent" | Project workspace upload dir; exact path shown in IDE file tree |
| **Codex CLI as host** | `-i` flag attaches to LLM context only | No filesystem path exposed. User must provide an explicit path (e.g., `~/Downloads/foo.png`). In-conversation pastes cannot be forwarded. |
| **Gemini CLI as host** | Varies by version | Prefer explicit paths over paste |
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`:
- Interactive terminal (stdin is a TTY): prompt user on stderr: `Estimated cost $X.XX. Proceed? (y/N)`. Decline → exit 1.
- Non-interactive (no TTY — agents, CI): no prompt is possible; exit 1 with a message naming `--yes`/`OMA_IMAGE_YES=1`. **Calling agents**: confirm the cost with the user in-conversation (`--dry-run` prints the estimate), then re-run with `-y`. Pass `-y` only when the run fits an existing budget authorization or newly approved spend.
## 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>]-<runShortid>[-<n>].<ext>` — the model segment is omitted when the vendor has no caller-visible model (`antigravity`), and `<ext>` reflects the magic-byte-sniffed format (`png`/`jpg`/`webp`/`gif`), not a fixed `.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
| Situation | Action |
|-----------|--------|
| No vendors authenticated | Exit 5, print `Run: oma image doctor` |
| Specific vendor unhealthy | Exit 5 with the vendor's setup guide (URL + env var + steps, rendered by `oma image doctor`) |
| All sub-strategies failed for a provider | Exit 1 with last classified error; include `strategy_attempts` in manifest |
| Timeout | Exit 6, manifest records `after_ms` |
| Cancelled (Ctrl+C/SIGTERM) | In-flight calls abort, failures are recorded as `timeout`, the manifest is written, and the command exits 6 when no provider succeeded |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |