SKILL: Configuring Custom Agents in OpenCode — native opencode.json config, OMO oh-my-opencode.json, markdown agent files

skill-opencode-custom-agents.md

Skill: Configuring Custom Agents in OpenCode

How to define custom agents natively in opencode and via oh-my-opencode.

---

Two Configuration Systems

OpenCode has its own native agent configuration, and oh-my-opencode (OMO) extends it with a separate config for its built-in agents. They coexist.

---

Native OpenCode Agent Configuration

Method 1: opencode.json

Add an "agent" key to ~/.config/opencode/opencode.json (global) or .opencode/opencode.json (project-local):

{
  "agent": {
    "reviewer": {
      "description": "Reviews code for correctness and style",
      "mode": "subagent",
      "model": "anthropic/claude-opus-4-6",
      "temperature": 0.1,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "implementer": {
      "description": "Implements features from specs",
      "mode": "primary",
      "model": "nvidia/qwen/qwen3.5-397b-a17b",
      "prompt": "{file:./prompts/implementer.md}",
      "steps": 100
    }
  }
}

Agent configuration fields:

Field	Type	Description
description	string	Required. Brief description shown in UI and used for agent routing
mode	"primary" | "subagent" | "all"	Primary = shows in Tab cycle; subagent = invoked via @agent
model	string	Override model in provider/model format
prompt	string	System prompt content or {file:./path/to/prompt.md} reference
tools	object	Per-tool true/false overrides
permission	array	Fine-grained permission rules (same format as opencode permission config)
temperature	float	0.0–1.0
top_p	float	Alternative diversity control
steps	int	Max agentic iterations before fallback to text-only
color	string	Hex #FF5733 or theme name for UI
hidden	bool	Hide from @ autocomplete (for internal subagents)

Method 2: Markdown Files

Create ~/.config/opencode/agents/<name>.md (global) or .opencode/agents/<name>.md (project):

---
description: Reviews code for correctness and style
mode: subagent
model: anthropic/claude-opus-4-6
temperature: 0.1
---

You are a code reviewer. Your job is to...

The YAML frontmatter holds the same config fields as the JSON approach. The body becomes the system prompt.

---

oh-my-opencode Agent Configuration

OMO uses a separate file ~/.config/opencode/oh-my-opencode.json to configure its built-in agents:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "sisyphus": {
      "model": "nvidia/qwen/qwen3.5-397b-a17b",
      "variant": "max"
    },
    "hephaestus": {
      "model": "nvidia/minimaxai/minimax-m2.1",
      "variant": "medium"
    },
    "oracle": {
      "model": "nvidia/qwen/qwen3-next-80b-a3b-thinking",
      "variant": "high"
    },
    "librarian": {
      "model": "nvidia/qwen/qwen3.5-397b-a17b"
    },
    "explore": {
      "model": "nvidia/qwen/qwen3-next-80b-a3b-instruct"
    },
    "prometheus": {
      "model": "nvidia/z-ai/glm4.7",
      "variant": "max"
    }
  },
  "categories": {
    "quick": {
      "model": "nvidia/qwen/qwen3-next-80b-a3b-instruct"
    },
    "ultrabrain": {
      "model": "nvidia/qwen/qwen3-next-80b-a3b-thinking",
      "variant": "xhigh"
    },
    "deep": {
      "model": "nvidia/z-ai/glm4.7",
      "variant": "medium"
    }
  },
  "disabled_hooks": [
    "category-skill-reminder"
  ]
}

variant values (provider-specific reasoning effort levels):

• minimal, low, medium, high, max, xhigh

---

opencode.json Full Structure

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-opencode@latest"],
  "provider": {
    "nvidia": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "NVIDIA NIM",
      "options": {
        "baseURL": "https://integrate.api.nvidia.com/v1"
      },
      "models": {
        "qwen/qwen3.5-397b-a17b": {
          "name": "Qwen 3.5 (Multimodal)",
          "limit": { "context": 262144, "output": 32768 },
          "parameters": {
            "temperature": 0.6,
            "top_p": 0.95,
            "top_k": 20,
            "chat_template_kwargs": { "enable_thinking": true }
          }
        }
      }
    }
  },
  "agent": {
    "my-custom-agent": { ... }
  }
}

---

Listing Available Agents

# List all configured agents (native + plugin agents)
opencode agent list

# Output includes agent name, mode (primary/subagent), and permission summary

---

Invoking Agents

# Via stock opencode run (exits after one turn)
opencode run --agent my-custom-agent "task description"

# Via OMO run (ralph wiggum loop — runs until todos complete)
npx oh-my-opencode run --agent hephaestus "task description"

# In TUI: Tab key cycles through primary agents; @agent-name invokes subagents

---

Pitfalls

❌ Agent not appearing in opencode agent list

• OMO's named agents (sisyphus, hephaestus, etc.) are loaded as part of the plugin, not shown as separate entries in opencode agent list. They're still valid --agent values for opencode run and npx oh-my-opencode run.
• Verify a custom native agent is registered by checking opencode agent list output — it should appear with its mode.

❌ Plugin not loading

The "plugin" field in opencode.json lists npm package names. Opencode resolves these from the node_modules directory inside ~/.config/opencode/. If the plugin is missing:

cd ~/.config/opencode && npm install
# or
cd ~/.config/opencode && bun install

Check ~/.config/opencode/package.json to see what's declared as a dep.

❌ --agent flag not recognized as custom agent

opencode run --agent works with both native agents (defined in opencode.json) and OMO agents. If the agent name isn't found, opencode falls back to the default model — it does NOT error. Check the session's "mode" field in opencode export output to confirm which agent actually ran.