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`:

```markdown
---
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:**
```bash
# 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
```bash
# Check if command appears in TUI
# Type "/" in OpenCode TUI and search for your command
```

### Verify Syntax
```bash
# 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`:
```json
{
  "permission": {
    "skill": {
      "*": "allow",
      "experimental-*": "ask",
      "internal-*": "deny"
    }
  }
}
```

### Agent-Specific Settings
```json
{
  "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*