OMO Agents — OpenCode Multi-Model Bridge

OMO bridges Claude Code to non-Claude models via OpenCode's agent system. Each agent has a specialized role, prompt structure, and output format. This skill routes by agent role, not by model.

Quick Dispatch

If {{ARGUMENTS}} starts with an agent name or --model, invoke it immediately via Bash — no deliberation needed:

/omo oracle "prompt"              → Bash: omo-agent oracle "prompt"
/omo explore "search query"       → Bash: omo-agent explore "search query"
/omo --model gpt "prompt"         → Bash: omo-agent --model gpt "prompt"
/omo --file img.png oracle "prompt" → Bash: omo-agent --file img.png oracle "prompt"
/omo                              → show agent catalog below for selection

Rule: If the first arg matches an agent name (oracle, explore, librarian, multimodal-looker) or is --model/--file, run omo-agent with all args directly. Do not ask which agent — the user already chose.

Agent Catalog

When to Use Which Agent

User Intent Routing

Model Routing

Use when you need a specific model rather than a role-based agent.

omo-agent --model <alias> "<prompt>"

See models-routing.md for detailed task-to-model mapping.

How to Invoke

All agents are invoked via Bash with the omo-agent wrapper. Do not use spawn_agent — it only uses Claude and cannot access OMO's non-Claude models.

Run Command

# Role agent
omo-agent <agent-name> "<prompt>"

# Model routing
omo-agent --model <alias> "<prompt>"

# Attach files
omo-agent --file /path/to/file.pdf oracle "<prompt>"

# Attach skill directory
omo-agent --skill /path/to/skill/ oracle "<prompt>"

Timeout: Always set Bash timeout to 600000 (10 min). Agents routinely take 1-5 minutes.

Parallel Agents (max 3 concurrent)

Fire multiple Bash tool calls simultaneously with run_in_background: true. Always collect all results before synthesizing.

Standard parallel patterns:

# Example: parallel research
omo-agent explore "<prompt>"    # run_in_background: true
omo-agent librarian "<prompt>"  # run_in_background: true
# Collect both results before synthesizing

Never parallelize sequential deps:

• Any review → fixes based on its findings

Execution Mode (Foreground vs Background)

When invoking a single agent, choose execution mode based on the task shape:

User override: If the user says --background or --wait, respect that over the heuristic.

x-skill default: When an x-skill dispatches agents, it should use foreground for single-agent queries and background only for parallel dispatch or explicitly long-running runs (e.g. --model codex autonomous deep work).

Model Routing Prompt Tips

When using --model, include output instructions in your prompt:

"[Your task description].

OUTPUT: Return ONLY the final answer as structured markdown. Do not include intermediate tool output. Do not delegate to other agents — answer directly."

Prompt Composition (Optional)

For complex or multi-step prompts, compose from reusable XML blocks instead of writing ad-hoc instructions. See references/prompt-blocks.md for the full block library and task-type selection guide.

Quick reference — which blocks for which task:

These blocks are guidance for prompt construction — they do NOT replace the [OUTPUT FORMAT] suffix that omo-agent auto-appends.

Error Handling

• Exit 0 = success, non-zero = failure
• "agent not found" / "is a subagent" = agent name issue → use one of: oracle, explore, librarian, multimodal-looker
• "Unknown agent" = not in valid list → see Agent Catalog above
• "default agent not found" = plugin compat issue → model mode uses --pure to avoid this
• Timeout = prompt too broad → break into smaller prompts

After Collecting Results

• Synthesize — extract key findings, never dump raw output
• Lead with the answer — conclusion first, details after
• Cite evidence — reference specific facts, URLs, file paths
• Flag uncertainty — note hedging or contradictions
• If an agent modified files, verify (tests, diagnostics)
• Contradictions between agents = flag for user decision

Gotchas

See gotchas.md for known failure patterns (UNAVAILABLE display-name agents, mode=subagent dispatch failures, --pure flag requirements, model fallback chains). Update it when you encounter new ones. Sibling skills (x-do, x-bugfix, etc.) reach into this file via ../x-omo/gotchas.md.

Task: {{ARGUMENTS}}