opencode/skill/opencode/command-creation.md

Command Creation Guide

Overview

OpenCode commands are user-invoked prompts for repetitive tasks, defined in the command/ directory.

File Location

• Default location (Global): ~/.config/opencode/command/<name>.md
• Project-specific: .opencode/command/<name>.md (when needed)

Command Structure

Each command file must contain YAML frontmatter followed by the prompt template.

Required Frontmatter Fields

• description: Brief description shown in TUI (1-2 sentences)

Optional Frontmatter Fields

• agent: Specific agent to execute this command
• model: Override default model
• subtask: Boolean to force subagent invocation

Template Features

The command template supports several placeholders:

• $ARGUMENTS: All arguments passed to the command
• $1, $2, $3: Individual positional arguments
• `!command: Execute bash command and inject output
• @filename: Include file content in prompt

Example Command

Create ~/.config/opencode/command/new-skill.md:

---
description: Create a new OpenCode skill with proper structure
---

Create a new OpenCode skill named "$ARGUMENTS" with comprehensive documentation.

**Skill Requirements:**
1. Directory: `skill/$ARGUMENTS/SKILL.md`
2. Frontmatter with `name` and `description`
3. Clear sections for usage, examples, best practices
4. Follow naming conventions: lowercase, hyphens, alphanumeric

**Steps:**
1. Create directory structure
2. Write SKILL.md with frontmatter
3. Include practical examples
4. Add troubleshooting section

Output the complete SKILL.md content for review.

Best Practices

Command Design

1. Clear Purpose: Each command should have a single, focused purpose
2. Descriptive Names: Use verbs that describe the action (e.g., create-, review-, analyze-)
3. Argument Handling: Use $ARGUMENTS or $1, $2 for flexible input
4. Error Handling: Include validation in prompts
5. Output Format: Structure responses for easy parsing

Naming Conventions

• Use kebab-case (lowercase with hyphens)
• Start with verb describing the action
• Keep names concise but descriptive

Quick Reference

Command Creation Checklist

• File name matches command name (kebab-case)
• Frontmatter includes description
• Template uses appropriate placeholders
• Includes examples of usage
• Tested with /command-name invocation

Common Patterns

Create a new command:

# Create command file
touch ~/.config/opencode/command/my-command.md

# Edit with template
cat > ~/.config/opencode/command/my-command.md << 'EOF'
---
description: Description of my command
---

Command template with $ARGUMENTS support.

Example: /my-command argument1 argument2
EOF

Testing and Validation

Test Command Loading

# Check if command appears in TUI
# Type "/" in OpenCode TUI and search for your command

Verify Syntax

# Check YAML frontmatter
head -20 command/my-command.md

Troubleshooting

Command Not Appearing

1. Check file location: Ensure command is in correct command/ directory
2. Verify frontmatter: Must have description field
3. Check permissions: No restrictive permissions blocking command
4. Restart OpenCode: Some changes require restart

Common Errors

• "Command not found": File not in correct location or missing .md extension
• "Invalid frontmatter": Missing required fields or YAML syntax error

Integration with OpenCode Config

Permissions Configuration

Add to opencode.json:

{
  "permission": {
    "skill": {
      "*": "allow",
      "experimental-*": "ask",
      "internal-*": "deny"
    }
  }
}

Agent-Specific Settings

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "analysis-*": "allow"
        }
      }
    }
  }
}

Response Guide for Command Creation Requests

When users ask to create commands, follow this structured approach:

1. 自动生成名称: 基于用户描述自动生成 kebab-case 命令名称
   • 从描述中提取关键词（动词+名词）
   • 转换为英文 kebab-case 格式
   • 如果名称已存在，添加数字后缀（如 -2, -3）
2. 验证名称: 确保名称符合 kebab-case 规范
3. 默认位置: 全局 (~/.config/opencode/command/) - commands are created here by default
4. 创建模板:
   • 生成包含 description 的 frontmatter
   • 创建支持 $ARGUMENTS 的模板
   • 包含使用示例
5. 写入文件: 创建命令文件并写入内容
6. 测试: 验证文件存在且格式正确

Sample Response Format:

我将帮你创建命令。

基于您的描述，自动生成名称：[generated-name]

**自动命名规则**:
- 从描述中提取关键词（动词+名词）
- 转换为 kebab-case 格式（小写字母、连字符）
- 检查名称冲突，自动添加数字后缀

**文件详情**:
- 名称: [generated-name]
- 用途: [brief-description]
- 位置: 全局 (~/.config/opencode/command/)

已创建 [file-path]：

```markdown
[complete file content]

要测试，请运行：[/command-name]

## Resources
- [OpenCode Commands Documentation](https://opencode.ai/docs/commands)
- [OpenCode Configuration Guide](https://opencode.ai/docs/config)

---

*Last updated: 2026-01-15*