Converting Claude Code Subagents to OpenCode Agents

This skill helps you convert Claude Code Subagent definitions (from .claude/agents/ or ~/.claude/agents/) to OpenCode Agent format (.opencode/agent/ or ~/.config/opencode/agent/).

Note: When running from a personal config that symlinks to ~/.config/opencode/, the agent files will be available globally.

Quick Reference

Source formats:

• Claude Code: .claude/agents/*.md or ~/.claude/agents/*.md
• JSON via CLI: --agents flag with JSON object

Target formats:

• OpenCode Markdown: .opencode/agent/*.md or ~/.config/opencode/agent/*.md
• OpenCode JSON: opencode.json config file

Key differences:

• Tools: Comma-separated string → Object with boolean values
• Mode: Implicit → Explicit mode field (primary, subagent, all)
• Permissions: Via tools only → Explicit permission field
• New fields: temperature, disable, mode

Conversion Workflow

Step 1: Locate Source Subagents

Find Claude Code subagents to convert:

# Project-level subagents
ls .claude/agents/

# User-level subagents
ls ~/.claude/agents/

Step 2: Read Source File

Read the subagent definition to understand its configuration:

cat .claude/agents/code-reviewer.md

Step 3: Map Configuration Fields

Convert each field from Claude Code format to OpenCode format:

Frontmatter mapping:

Claude Code	OpenCode	Notes
name	filename or name in JSON	Filename becomes agent name in markdown
description	description	Keep identical
tools	tools	Convert format (see below)
model	model	Keep identical, adjust defaults
n/a	mode	Add explicit mode: subagent (default), primary, or all
n/a	temperature	Optional: Set 0.0-1.0 for response variability
n/a	disable	Optional: Set true to disable agent
n/a	permission	Optional: Set granular permissions

Tool format conversion:

Claude Code (comma-separated or omitted):

tools: Read, Grep, Glob, Bash

OpenCode (object with booleans):

tools:
  read: true
  grep: true
  glob: true
  bash: true
  write: false
  edit: false

If tools field is omitted in Claude Code: It inherits all tools. In OpenCode, either omit the tools field entirely or set all desired tools to true.

Model mapping:

Claude Code models:

• sonnet, opus, haiku (aliases)
• 'inherit' (use main conversation model)

OpenCode models:

• Full provider/model format: anthropic/claude-sonnet-4-20250514
• Can use same aliases if configured in OpenCode

Step 4: Add OpenCode-Specific Features

Consider adding these optional fields:

Temperature:

temperature: 0.1  # Lower = more focused, higher = more creative

Mode:

mode: subagent  # or 'primary' or 'all'

Permissions:

permission:
  edit: ask      # Options: ask, allow, deny
  bash:
    "git push": ask
    "git status": allow
    "*": ask
  webfetch: deny

Step 5: Create Target File

Option A: Markdown format (recommended for easy editing)

Create file at .opencode/agent/<agent-name>.md:

---
description: Expert code reviewer focusing on quality and security
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  read: true
  grep: true
  glob: true
  bash: true
  write: false
  edit: false
permission:
  edit: deny
  bash: ask
---

[System prompt content from original Claude Code subagent]

Option B: JSON format (for programmatic access)

Add to opencode.json:

{
  "agent": {
    "code-reviewer": {
      "description": "Expert code reviewer focusing on quality and security",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.1,
      "prompt": "{file:./prompts/code-review.txt}",
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "bash": true,
        "write": false,
        "edit": false
      },
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

Step 6: Validate Conversion

Check the converted agent:

1. Verify file location:

   • Project agent: .opencode/agent/ directory exists and file is present
   • Global agent: ~/.config/opencode/agent/ directory exists and file is present

2. Verify frontmatter:

   • Description is clear and specific
   • Mode is set appropriately
   • Tools are properly formatted as object with booleans
   • Model string is valid

3. Verify system prompt:

   • All content from original agent is preserved
   • No YAML frontmatter markers in the prompt body

4. Test the agent:

   • Use @agent-name to invoke the agent
   • Verify it behaves as expected

Conversion Examples

For detailed step-by-step examples with before/after comparisons, see:

cat EXAMPLES.md

The EXAMPLES.md file includes:

• Code Reviewer (read-only agent)
• Debugger (with edit access)
• Test Runner (with bash permissions)
• Documentation Writer (write-only)
• Security Auditor (analysis only)
• Data Analyst (with BigQuery)
• Primary Build Agent (full access)
• Batch conversion scripts
• Complex permission examples

Quick example snippet:

Claude Code format:

---
name: code-reviewer
description: Reviews code for quality and security
tools: Read, Grep, Glob
model: sonnet
---

OpenCode format:

---
description: Reviews code for quality and security
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  read: true
  grep: true
  glob: true
  write: false
  edit: false
permission:
  edit: deny
---

Common Conversion Patterns

Pattern 1: Read-Only Analysis Agent

Claude Code:

tools: Read, Grep, Glob

OpenCode:

mode: subagent
tools:
  read: true
  grep: true
  glob: true
  write: false
  edit: false
  bash: false
permission:
  edit: deny
  bash: deny

Pattern 2: Development Agent with Full Access

Claude Code:

tools:  # Omitted = inherits all

OpenCode:

mode: subagent
# Omit tools field to inherit all, or:
tools:
  read: true
  write: true
  edit: true
  bash: true
  grep: true
  glob: true
permission:
  bash:
    "rm *": ask
    "git push": ask
    "*": allow

Pattern 3: Selective Bash Permissions

Claude Code:

tools: Bash, Read

OpenCode:

mode: subagent
tools:
  bash: true
  read: true
  write: false
  edit: false
permission:
  bash:
    "git status": allow
    "git diff*": allow
    "git log*": allow
    "npm test": allow
    "npm run*": allow
    "*": ask  # All other commands require approval

Special Considerations

Built-in Agents

Claude Code has built-in agents like the "Plan" subagent. OpenCode also has built-in agents:

• Build: Primary agent with all tools (equivalent to Claude Code default)
• Plan: Primary agent with restricted tools (similar to Claude Code Plan subagent)
• General: Subagent for complex research (similar to Claude Code general-purpose usage)

Don't convert built-in agents - they already exist in OpenCode with similar functionality.

CLI-Defined Agents

Claude Code supports CLI-defined agents via --agents flag:

claude --agents '{
  "code-reviewer": {
    "description": "...",
    "prompt": "...",
    "tools": ["Read", "Grep"],
    "model": "sonnet"
  }
}'

OpenCode equivalent: Pass configuration via environment or config file. No direct CLI equivalent, but you can:

1. Define in opencode.json for persistence
2. Use project-specific .opencode/agent/ files
3. Use global ~/.config/opencode/agent/ files

Tool Name Differences

Most tools have the same names, but watch for:

• Claude Code: Bash, Read, Write, Edit, Grep, Glob
• OpenCode: bash, read, write, edit, grep, glob (lowercase in YAML)

In OpenCode markdown frontmatter, use lowercase. In JSON, also lowercase.

MCP Tools

Both systems support MCP (Model Context Protocol) tools:

• Claude Code: Subagents inherit MCP tools when tools field is omitted
• OpenCode: Same behavior, plus wildcard control: mymcp_*: false

When converting, if the Claude Code agent uses MCP tools:

# OpenCode - allow specific MCP server tools
tools:
  read: true
  myserver_*: true  # All tools from 'myserver' MCP
  write: false

Resumable Agents

Claude Code supports resumable subagents via agentId and resume parameter. OpenCode uses session-based continuity with parent/child session navigation:

• Ctrl+Right: Cycle forward through sessions
• Ctrl+Left: Cycle backward through sessions

Conversion strategy:

• Claude Code's resumable agents → OpenCode's session continuity (automatic)
• No configuration changes needed
• Sessions are tracked automatically in OpenCode

Validation Checklist

After conversion, verify:

• File is in correct location (.opencode/agent/ or ~/.config/opencode/agent/)
• Frontmatter has description (required)
• mode is set to subagent, primary, or all (defaults to all if omitted)
• tools field uses object format with booleans (or omitted to inherit all)
• model string is valid for your OpenCode provider configuration
• System prompt is preserved exactly from original
• No name field in frontmatter (filename is the name)
• temperature is set if behavioral control is important
• permission is configured for potentially destructive tools
• Test agent invocation with @agent-name

Troubleshooting

Issue: Agent not appearing in OpenCode

• Check file is in correct directory (.opencode/agent/ or ~/.config/opencode/agent/)
• Verify frontmatter YAML is valid
• Ensure description field is present
• Check for disable: true in frontmatter

Issue: Tools not working as expected

• Verify tools object format (not comma-separated string)
• Check permissions aren't blocking tool usage
• Ensure tool names are lowercase

Issue: Agent behaves differently than in Claude Code

• Review temperature setting (may need adjustment)
• Check permission settings (may be blocking operations)
• Verify system prompt is identical to original

Issue: Model errors

• Verify model string format: provider/model-name
• Check provider is configured in OpenCode
• Try using inherit if main model should be used

Best Practices

1. Start with read-only agents: Convert agents without write access first to minimize risk
2. Use markdown format: Easier to edit and maintain than JSON
3. Set explicit permissions: Don't rely on tool restrictions alone
4. Test incrementally: Convert one agent at a time and test before converting more
5. Document changes: Note any behavioral differences in agent comments
6. Use temperature: Set appropriate temperature for agent's task type
7. Leverage wildcards: Use glob patterns for tool and permission management
8. Keep system prompts identical: Don't modify the prompt during conversion
9. Use project agents: Place in .opencode/agent/ for team sharing
10. Version control: Commit converted agents to git for team consistency

Related Commands

• opencode agent create - Create a new agent with guided setup
• View agents: Check .opencode/agent/ or ~/.config/opencode/agent/
• Test agent: Use @agent-name in OpenCode conversation
• Switch primary agents: Use Tab key or configured keybind

References

• OpenCode Agents Documentation
• Claude Code Subagents Documentation