Converting Claude Code Subagents to OpenCode Agents

This skill helps you convert Claude Code Subagent definitions (from

.claude/agents/

~/.claude/agents/

.opencode/agent/

~/.config/opencode/agent/

Note: When running from a personal config that symlinks to

~/.config/opencode/

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:

name

name

description

description

tools

tools

model

model

mode

subagent

primary

all

temperature

disable

true

permission

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

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

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

resume

• 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