convertCommands

Converting Claude Code Slash Commands to OpenCode Commands

This skill helps you convert Claude Code slash command definitions (from .claude/commands/ or ~/.claude/commands/) to OpenCode command format (.opencode/command/ or ~/.config/opencode/command/).

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

Quick Reference

Source formats:

• Claude Code: .claude/commands/*.md or ~/.claude/commands/*.md

Target formats:

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

Key differences:

• Frontmatter fields: Different field names and options
• Argument syntax: Same ($ARGUMENTS, $1, $2, etc.)
• Shell commands: Same syntax (!command``)
• File references: Same syntax (@filename)
• New fields: subtask, template (in JSON)

Conversion Workflow

Step 1: Locate Source Commands

Find Claude Code slash commands to convert:

# Project-level commands
ls .claude/commands/

# User-level commands
ls ~/.claude/commands/

Step 2: Read Source File

Read the command definition to understand its configuration:

cat .claude/commands/review.md

Step 3: Map Configuration Fields

Convert each field from Claude Code format to OpenCode format:

Frontmatter mapping:

Tool conversion:

Claude Code uses allowed-tools to restrict which tools the command can use:

allowed-tools: Bash(git add:*), Bash(git status:*), Read

OpenCode uses agent to specify which agent runs the command:

agent: build

Step 4: Handle Special Cases

Bash commands with allowed-tools:

Claude Code:

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

OpenCode - Use agent with appropriate permissions:

---
description: Create a git commit
agent: build
---

Note: OpenCode handles tool permissions at the agent level, not command level.

Model invocation control:

Claude Code:

---
disable-model-invocation: true
---

OpenCode doesn't have a direct equivalent. Commands are always user-invoked in OpenCode.

Step 5: Create Target File

Option A: Markdown format (recommended for easy editing)

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

---
description: Review code for quality and security
agent: build
model: anthropic/claude-sonnet-4-20250514
---

Review this code for:

- Security vulnerabilities
- Performance issues
- Code style violations

Use !`git diff HEAD` to see current changes.

Option B: JSON format (for programmatic access)

Add to opencode.json:

{
  "command": {
    "review": {
      "description": "Review code for quality and security",
      "template": "Review this code for:\n- Security vulnerabilities\n- Performance issues\n- Code style violations\n\nUse !`git diff HEAD` to see current changes.",
      "agent": "build",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

Step 6: Validate Conversion

Check the converted command:

1. Verify file location:

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

2. Verify frontmatter:

   • Description is clear and specific
   • Agent is set appropriately (if needed)
   • Model string is valid (if specified)

3. Verify command content:

   • All content from original command is preserved
   • Arguments ($ARGUMENTS, $1, etc.) are preserved
   • Shell commands (!command``) are preserved
   • File references (@filename) are preserved

4. Test the command:

   • Use /command-name to invoke the command
   • 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:

• Simple code review command
• Git commit command with bash execution
• PR review with arguments
• Test runner command
• Documentation generator
• Batch conversion scripts
• Complex permission examples

Quick example snippet:

Claude Code format:

---
description: Review code for quality and security
allowed-tools: Read, Grep, Glob
model: claude-3-5-sonnet-20241022
---
Review this code focusing on security and performance.

OpenCode format:

---
description: Review code for quality and security
agent: plan
model: anthropic/claude-3-5-sonnet-20241022
---
Review this code focusing on security and performance.

Common Conversion Patterns

Pattern 1: Simple Review Command

Claude Code:

---
description: Review this code
allowed-tools: Read, Grep
---
Review this code for bugs and improvements.

OpenCode:

---
description: Review this code
agent: plan
---
Review this code for bugs and improvements.

Pattern 2: Git Commit Command

Claude Code:

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

Current status: !`git status`
Current diff: !`git diff HEAD`

Create a commit based on these changes.

OpenCode:

---
description: Create a git commit
agent: build
---

Current status: !`git status`
Current diff: !`git diff HEAD`

Create a commit based on these changes.

Pattern 3: Command with Arguments

Claude Code:

---
argument-hint: [pr-number] [priority]
description: Review pull request
---

Review PR #$1 with priority $2.

OpenCode:

---
description: Review pull request
---
Review PR #$1 with priority $2.

Note: argument-hint is not supported in OpenCode, but the argument placeholders work the same.

Pattern 4: Subagent Invocation

Claude Code: No direct equivalent - commands run in main conversation.

OpenCode:

---
description: Analyze performance
agent: plan
subtask: true
---
Analyze performance issues in this codebase.

The subtask: true forces this to run as a subagent invocation.

Special Considerations

Argument Hints

Claude Code supports argument-hint to show expected arguments:

argument-hint: [message]

OpenCode doesn't have this field. Document expected arguments in the command description instead:

description: Create git commit [message]

Allowed Tools vs Agents

Claude Code controls tools at the command level with allowed-tools.

OpenCode controls tools at the agent level. Choose the appropriate agent for your command:

• build - Full access to all tools
• plan - Restricted tools for analysis
• Custom agents - Your defined agents

Model Strings

Both systems use similar model strings, but ensure you use the correct provider prefix:

Claude Code:

model: claude-3-5-sonnet-20241022

OpenCode:

model: anthropic/claude-3-5-sonnet-20241022

Namespacing with Subdirectories

Both systems support organizing commands in subdirectories:

Claude Code: .claude/commands/frontend/component.md → /component with description showing "(project:frontend)"

OpenCode: .opencode/command/frontend/component.md → /frontend/component

Note: OpenCode includes the subdirectory in the command name, while Claude Code shows it in the description only.

File References

Both systems use the same @ syntax for file references:

Review the component in @src/components/Button.tsx

This works identically in both systems.

Shell Command Execution

Both systems use the same !`command` syntax:

Current git status: !`git status`

This works identically in both systems.

Thinking Mode

Claude Code supports extended thinking via keywords in command content.

OpenCode doesn't have a specific thinking mode configuration for commands. Extended thinking is model-dependent.

Validation Checklist

After conversion, verify:

• File is in correct location (.opencode/command/ or ~/.config/opencode/command/)
• Frontmatter has description (optional but recommended)
• Command content is preserved exactly from original
• Argument placeholders ($ARGUMENTS, $1, etc.) are preserved
• Shell commands (!`command`) are preserved
• File references (@filename) are preserved
• Model string uses correct provider prefix (if specified)
• Agent is appropriate for command's needs (if specified)
• Test command invocation with /command-name

Troubleshooting

Issue: Command not appearing in OpenCode

• Check file is in correct directory (.opencode/command/ or ~/.config/opencode/command/)
• Verify frontmatter YAML is valid (if present)
• Try restarting OpenCode

Issue: Arguments not working

• Verify you're using $ARGUMENTS, $1, $2, etc. (not {arg1} or other syntax)
• Check argument is being passed when invoking command

Issue: Shell commands not executing

• Verify syntax: !`command` (backticks inside the ! markers)
• Check the shell command works when run manually
• Ensure agent has bash tool permissions

Issue: File references not working

• Verify syntax: @path/to/file.ext
• Check the file path is correct relative to project root

Issue: Model errors

• Verify model string format: provider/model-name
• Check provider is configured in OpenCode
• Try using model: inherit or omit the field

Issue: Command runs in wrong context

• Set subtask: true to force subagent invocation
• Choose appropriate agent for the command

Best Practices

1. Start simple: Convert basic commands first to understand the process
2. Use markdown format: Easier to edit and maintain than JSON
3. Choose appropriate agents: Use plan for analysis, build for modifications
4. Preserve command content: Don't modify the prompt during conversion
5. Test incrementally: Convert one command at a time and test before converting more
6. Document arguments: Since argument-hint isn't supported, document in description
7. Organize with subdirectories: Keep related commands together
8. Use project commands: Place in .opencode/command/ for team sharing
9. Version control: Commit converted commands to git for team consistency
10. Keep it simple: Commands should be focused and single-purpose

Related Commands

• View commands: Check .opencode/command/ or ~/.config/opencode/command/
• Test command: Use /command-name in OpenCode TUI
• Built-in commands: /help, /init, /undo, /redo, /share

References

• OpenCode Commands Documentation
• Claude Code Slash Commands Documentation