opencode/skill/opencode/skill-creation.md

Skill Creation Guide

Overview

OpenCode skills are reusable behavior definitions for agents, defined in skill/<name>/SKILL.md files.

Directory Structure

Default location (Global):

~/.config/opencode/skill/
└── <skill-name>/
    └── SKILL.md

Project-specific location (when needed):

.opencode/skill/
└── <skill-name>/
    └── SKILL.md

Skill File Requirements

Frontmatter (Required)

• name: Skill name (must match directory name)
• description: Concise description (1-1024 characters)

Frontmatter (Optional)

• license: License identifier
• compatibility: Compatibility constraints
• metadata: Key-value pairs for additional context

Naming Rules

Skill names must:

• Be 1-64 characters
• Use lowercase alphanumeric with single hyphens
• Not start or end with hyphen
• Not contain consecutive hyphens
• Match regex: ^[a-z0-9]+(-[a-z0-9]+)*$

Skill Content Structure

A well-structured skill should include:

1. Introduction: Purpose and scope
2. Usage Instructions: When and how to use the skill
3. Examples: Practical implementation examples
4. Best Practices: Recommended approaches
5. Troubleshooting: Common issues and solutions
6. References: Related documentation

Example Skill Template

---
name: example-skill
description: Brief description of what this skill does
---

# Skill Title

## Purpose
Explain what this skill helps achieve and when to use it.

## Core Concepts
- Key principle 1
- Key principle 2

## Usage
Step-by-step instructions for using this skill.

## Examples
### Basic Example
```bash
# Example code or commands

Advanced Example

Detailed example with explanation.

Best Practices

1. Recommended approach 1
2. Recommended approach 2

Troubleshooting

Issue	Solution
Common problem	How to fix it

References

• Documentation link
• Related skills or commands

## Best Practices

### Skill Development
1. **Modular Design**: Keep skills focused on specific domains
2. **Comprehensive Documentation**: Include examples and edge cases
3. **Consistent Formatting**: Follow existing skill patterns
4. **Testing**: Verify skill loads correctly with `skill({ name: "skill-name" })`
5. **Version Control**: Track skill changes in Git

### Organization
1. **Default location**: Global (`~/.config/opencode/skill/`) - skills are created here by default for reuse across projects
2. **Naming Conventions**: Use kebab-case for all skill names
3. **Documentation**: Maintain README or index of available skills
4. **Permissions**: Configure access controls in `opencode.json`

## Quick Reference

### Skill Creation Checklist
- [ ] Directory name matches skill name
- [ ] SKILL.md contains required frontmatter
- [ ] Description is 1-1024 characters
- [ ] Name follows naming rules
- [ ] Content includes usage and examples
- [ ] Skill loads without errors

### Common Patterns

**Create a new skill:**
```bash
# Create skill directory
mkdir -p ~/.config/opencode/skill/my-skill

# Create SKILL.md
cat > ~/.config/opencode/skill/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Description of my skill
---

# My Skill

## Usage
Instructions here.

## Examples
Example content.
EOF

Testing and Validation

Test Skill Loading

# In OpenCode session
skill({ name: "my-skill" })

Verify Syntax

# Check YAML frontmatter
head -20 skill/my-skill/SKILL.md

# Validate naming
echo "skill-name" | grep -E '^[a-z0-9]+(-[a-z0-9]+)*$'

Troubleshooting

Skill Not Loading

1. Directory name: Must match skill name in frontmatter
2. File name: Must be SKILL.md (all caps)
3. Frontmatter: Requires name and description
4. Naming rules: Verify name follows conventions
5. Permissions: Check opencode.json permissions

Common Errors

• "Skill not found": Directory name mismatch or missing SKILL.md
• "Invalid frontmatter": Missing required fields or YAML syntax error
• "Permission denied": Skill blocked by permission configuration

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 Skill Creation Requests

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

1. 自动生成名称: 基于用户描述自动生成 skill 名称
   • 从描述中提取核心功能关键词
   • 转换为小写字母、连字符格式
   • 如果名称已存在，添加数字后缀
2. 验证名称: 确保名称符合命名规则（小写字母、连字符、字母数字）
3. 默认位置: 全局 (~/.config/opencode/skill/<name>/) - skills are created here by default
4. 创建 SKILL.md:
   • 包含 name 和 description 的 frontmatter
   • 结构化内容：Purpose, Usage, Examples, Best Practices, Troubleshooting
5. 写入文件: 创建完整的 SKILL.md 文件
6. 测试: 验证技能可正常加载 skill({ name: "<skill-name>" })

Sample Response Format:

我将帮你创建技能。

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

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

**文件详情**:
- 名称: [generated-name]
- 主要功能: [brief-description]
- 位置: 全局 (~/.config/opencode/skill/)

已创建 [file-path]：

```markdown
[complete file content]

要测试，请运行：skill({ name: "skill-name" })

## Resources
- [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
- [OpenCode Configuration Guide](https://opencode.ai/docs/config)
- [GitHub Repository](https://github.com/anomalyco/opencode)

---

*Last updated: 2026-01-15*