--- name: convertSubagents description: Atlas skill for converting Claude Code Subagents to OpenCode Agents format. USE WHEN migrating from Claude Code to OpenCode or when you have existing subagent definitions to port. context: fork --- # 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: ```bash # 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: ```bash 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): ```yaml tools: Read, Grep, Glob, Bash ``` OpenCode (object with booleans): ```yaml 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:** ```yaml temperature: 0.1 # Lower = more focused, higher = more creative ``` **Mode:** ```yaml mode: subagent # or 'primary' or 'all' ``` **Permissions:** ```yaml 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/.md`: ```markdown --- 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`: ```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: ```bash 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: ```yaml --- name: code-reviewer description: Reviews code for quality and security tools: Read, Grep, Glob model: sonnet --- ``` OpenCode format: ```yaml --- 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:** ```yaml tools: Read, Grep, Glob ``` **OpenCode:** ```yaml 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:** ```yaml tools: # Omitted = inherits all ``` **OpenCode:** ```yaml 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:** ```yaml tools: Bash, Read ``` **OpenCode:** ```yaml 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: ```bash 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: ```yaml # 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](https://opencode.ai/docs/agents/) - [Claude Code Subagents Documentation](https://code.claude.com/docs/en/sub-agents)