convertSubagents

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:

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