skill-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creation for OpenCode

OpenCode 技能创建

Create reusable, discoverable skills that extend OpenCode's capabilities through on-demand loading.

创建可重复使用、可被发现的Skill，通过按需加载扩展OpenCode的能力。

What Skills Are

什么是Skill

Skills are modular instruction sets that OpenCode agents can load when needed. Each skill provides:

Specialized workflows - Multi-step procedures for specific domains
Domain expertise - Project-specific knowledge, schemas, conventions
Tool integrations - Instructions for working with specific formats or APIs
Bundled resources - Scripts, references, and assets for complex tasks

Skills use progressive disclosure: agents see skill names and descriptions initially, then load full content only when triggered by relevant user requests.

Skill是OpenCode Agent可按需加载的模块化指令集。每个Skill提供：

专业工作流 - 特定领域的多步骤流程
领域专业知识 - 项目专属知识、模式、约定
工具集成 - 与特定格式或API协作的说明
捆绑资源 - 用于复杂任务的脚本、参考资料和资产

Skill采用**渐进式披露（progressive disclosure）**机制：Agent最初仅能看到Skill的名称和描述，只有当相关用户请求触发时，才会加载完整内容。

Quick Start

快速入门

Create a skill in three steps:

Create directory structure:

bash

mkdir -p .opencode/skills/my-skill
cd .opencode/skills/my-skill
touch SKILL.md

Add frontmatter to

SKILL.md

yaml

---
name: my-skill
description: This skill should be used when the user asks to "do X", "configure Y", or needs Z guidance.
---

Add markdown content below frontmatter explaining what the skill does and how to use it.

That's it! OpenCode will automatically discover and offer the skill to agents.

分三步创建Skill：

创建目录结构:

bash

mkdir -p .opencode/skills/my-skill
cd .opencode/skills/my-skill
touch SKILL.md

为
SKILL.md
添加frontmatter:

yaml

---
name: my-skill
description: This skill should be used when the user asks to "do X", "configure Y", or needs Z guidance.
---

在frontmatter下方添加Markdown内容，说明该Skill的功能和使用方法。

完成以上步骤即可！OpenCode会自动发现该Skill并提供给Agent使用。

File Locations

文件位置

OpenCode searches for skills in these locations (in order):

Project-local (searches up to git worktree):

```
.opencode/skills/<name>/SKILL.md
```
```
.claude/skills/<name>/SKILL.md
```
```
.agents/skills/<name>/SKILL.md
```

Global (user-wide):

~/.config/opencode/skills/<name>/SKILL.md

```
~/.claude/skills/<name>/SKILL.md
```
```
~/.agents/skills/<name>/SKILL.md
```

Use project-local for repository-specific workflows. Use global for general-purpose skills.

OpenCode会按以下顺序在这些位置搜索Skill：

项目本地（搜索范围上限为Git工作区）:

```
.opencode/skills/<name>/SKILL.md
```
```
.claude/skills/<name>/SKILL.md
```
```
.agents/skills/<name>/SKILL.md
```

全局（用户级）:

~/.config/opencode/skills/<name>/SKILL.md

```
~/.claude/skills/<name>/SKILL.md
```
```
~/.agents/skills/<name>/SKILL.md
```

项目本地Skill适用于仓库专属工作流，全局Skill适用于通用场景。

Skill Creation Workflow

Skill创建工作流

Step 1: Understand the Use Case

步骤1：明确使用场景

Before creating a skill, clarify:

What problem does it solve? - Identify specific user requests or workflows
What would users say? - Collect concrete trigger phrases
What context is needed? - Determine required domain knowledge

Example: For a

git-release

skill, users might say "create a release", "draft changelog", or "tag a new version".

创建Skill前，需明确以下内容：

解决什么问题？ - 识别具体的用户请求或工作流
用户会怎么说？ - 收集具体的触发短语
需要什么上下文？ - 确定所需的领域知识

示例：针对

git-release

Skill，用户可能会说「创建版本」「生成变更日志草稿」「标记新版本」。

Step 2: Plan the Structure

步骤2：规划结构

Decide what resources the skill needs:

SKILL.md only - Simple knowledge, no complex resources
SKILL.md + references/ - Detailed docs, schemas, API specs
SKILL.md + examples/ - Working code samples users can copy
SKILL.md + scripts/ - Utility scripts for validation or automation

Most skills benefit from the standard structure (SKILL.md + references/).

确定Skill所需的资源：

仅SKILL.md - 简单知识，无复杂资源
SKILL.md + references/ - 详细文档、模式、API规范
SKILL.md + examples/ - 用户可直接复制的可运行代码示例
SKILL.md + scripts/ - 用于验证或自动化的实用脚本

大多数Skill采用标准结构（SKILL.md + references/）即可满足需求。

Step 3: Create Directories

步骤3：创建目录

Create the skill directory and subdirectories:

bash

undefined

bash

undefined

Minimal skill

最简Skill

mkdir -p .opencode/skills/skill-name

Standard skill (recommended)

标准Skill（推荐）

mkdir -p .opencode/skills/skill-name/references

Complete skill

完整Skill

mkdir -p .opencode/skills/skill-name/{references,examples,scripts}


Always start with the minimal or standard structure. Add examples/ and scripts/ only when needed.

mkdir -p .opencode/skills/skill-name/{references,examples,scripts}


始终从最简或标准结构开始，仅在需要时添加examples/和scripts/。

Step 4: Write Frontmatter

步骤4：编写Frontmatter

Every

SKILL.md

must begin with YAML frontmatter containing at minimum

name

and

description

Required fields:

yaml

---
name: skill-name
description: This skill should be used when the user asks to "trigger phrase 1", "trigger phrase 2", or needs specific guidance.
---

Name requirements:

1-64 characters
Lowercase alphanumeric with single hyphens
Must match directory name
Pattern:
```
^[a-z0-9]+(-[a-z0-9]+)*$
```

Description requirements:

1-1024 characters
Include specific trigger phrases in quotes
Be concrete about when to use the skill
Helps agents decide whether to load the skill

Optional fields:

yaml

---
name: skill-name
description: ...
license: MIT
compatibility: opencode
metadata:
  author: Your Name
  version: 1.0.0
---

For complete frontmatter specification, see

references/frontmatter-spec.md

每个

SKILL.md

必须以YAML frontmatter开头，至少包含

name

和

description

字段。

必填字段:

yaml

---
name: skill-name
description: This skill should be used when the user asks to "trigger phrase 1", "trigger phrase 2", or needs specific guidance.
---

名称要求:

1-64个字符
小写字母、数字及单个连字符
必须与目录名称一致
格式：
```
^[a-z0-9]+(-[a-z0-9]+)*$
```

描述要求:

1-1024个字符
包含带引号的具体触发短语
明确说明Skill的使用场景
帮助Agent判断是否加载该Skill

可选字段:

yaml

---
name: skill-name
description: ...
license: MIT
compatibility: opencode
metadata:
  author: Your Name
  version: 1.0.0
---

完整的frontmatter规范请参考

references/frontmatter-spec.md

。

Step 5: Write Body Content

步骤5：编写正文内容

After frontmatter, write markdown content explaining:

Essential sections:

Overview - What the skill provides (2-3 sentences)
Core procedures - Step-by-step workflows
Key concepts - Domain-specific knowledge agents need
Quick reference - Tables, commands, or patterns

Keep it focused:

Target 1,500-2,000 words
Focus on essential procedures
Move detailed content to references/
Use clear headings and examples

Writing style:

Use imperative form: "Configure the setting" not "You should configure"
Be direct and actionable
Include code examples where helpful
Reference bundled resources clearly

在frontmatter之后，编写Markdown内容，包含以下部分：

核心章节:

概述 - Skill的功能介绍（2-3句话）
核心流程 - 分步工作流
关键概念 - Agent所需的领域专属知识
快速参考 - 表格、命令或模式

保持内容聚焦:

目标字数1500-2000字
聚焦核心流程
将详细内容移至references/
使用清晰的标题和示例

写作风格:

使用祈使句：「配置设置」而非「你应该配置设置」
直接且可执行
必要时包含代码示例
清晰引用捆绑资源

Step 6: Add Bundled Resources

步骤6：添加捆绑资源

Organize supporting materials by type:

references/ - Documentation loaded as needed:

Detailed patterns and techniques
API documentation
Schema definitions
Troubleshooting guides
Each file: 2,000-5,000+ words

examples/ - Working code users can copy:

Complete, runnable scripts
Configuration files
Template files
Real-world usage examples

scripts/ - Utility scripts:

Validation tools
Testing helpers
Automation scripts
Must be executable

Reference resources in SKILL.md:

markdown

undefined

按类型组织支持材料：

references/ - 按需加载的文档:

详细模式和技术
API文档
模式定义
故障排除指南
每个文件：2000-5000+字

examples/ - 用户可复制的可运行代码:

完整的可运行脚本
配置文件
模板文件
真实场景使用示例

scripts/ - 实用脚本:

验证工具
测试辅助工具
自动化脚本
必须可执行

在SKILL.md中引用资源:

markdown

undefined

Additional Resources

额外资源

Reference Files

参考文件

For detailed information, consult:

references/patterns.md
- Common patterns and best practices
references/api-reference.md
- Complete API documentation

如需详细信息，请查阅：

references/patterns.md
- 常见模式与最佳实践
references/api-reference.md
- 完整API文档

Example Files

示例文件

Working examples in

examples/

example-config.json
- Sample configuration
example-script.sh
- Usage demonstration


For progressive disclosure strategy, see `references/progressive-disclosure.md`.

examples/

中的可运行示例：

example-config.json
- 示例配置
example-script.sh
- 使用演示


渐进式披露策略请参考`references/progressive-disclosure.md`。

Step 7: Validate and Test

步骤7：验证与测试

Before using your skill:

Validate structure:

bash

undefined

使用Skill前，请完成以下步骤：

验证结构:

bash

undefined

Run validation script

运行验证脚本

.opencode/skills/skill-creation/scripts/validate-skill.sh .opencode/skills/your-skill


**Check manually**:
- [ ] SKILL.md exists with valid YAML frontmatter
- [ ] Frontmatter has `name` and `description`
- [ ] Name matches directory name
- [ ] Name follows pattern: `^[a-z0-9]+(-[a-z0-9]+)*$`
- [ ] Description is 1-1024 characters
- [ ] Description includes specific trigger phrases
- [ ] All referenced files exist

**Test with OpenCode**:
1. Start a new OpenCode session
2. Ask a question using trigger phrases from description
3. Verify skill appears in available skills
4. Confirm skill loads correctly
5. Check if content is helpful for the task

**Iterate**:
- Use the skill on real tasks
- Notice gaps or unclear instructions
- Update SKILL.md or references/
- Re-test and refine

.opencode/skills/skill-creation/scripts/validate-skill.sh .opencode/skills/your-skill


**手动检查**:
- [ ] SKILL.md存在且包含有效的YAML frontmatter
- [ ] Frontmatter包含`name`和`description`
- [ ] 名称与目录名称一致
- [ ] 名称符合格式：`^[a-z0-9]+(-[a-z0-9]+)*$`
- [ ] 描述字数在1-1024之间
- [ ] 描述包含具体触发短语
- [ ] 所有引用的文件均存在

**使用OpenCode测试**:
1. 启动新的OpenCode会话
2. 使用描述中的触发短语提问
3. 验证Skill是否出现在可用技能列表中
4. 确认Skill加载正常
5. 检查内容是否对任务有帮助

**迭代优化**:
- 在真实任务中使用Skill
- 发现内容缺口或说明模糊的地方
- 更新SKILL.md或references/
- 重新测试并完善

Frontmatter Essentials

Frontmatter要点

Required Fields

必填字段

name - Skill identifier

Must match directory name
1-64 characters
Lowercase alphanumeric with single hyphens
Pattern:
```
^[a-z0-9]+(-[a-z0-9]+)*$
```
Examples:
```
git-release
```
,
```
api-design
```
,
```
frontend-testing
```

description - When to use the skill

1-1024 characters
Include specific trigger phrases users would say
Be concrete about use cases
Determines when agents load the skill

Good description:

yaml

description: This skill should be used when the user asks to "create a database schema", "design SQL tables", "optimize queries", or needs guidance on relational database design.

Bad description:

yaml

description: Helps with databases.  # Too vague, no trigger phrases

name - Skill标识符

必须与目录名称一致
1-64个字符
小写字母、数字及单个连字符
格式：
```
^[a-z0-9]+(-[a-z0-9]+)*$
```
示例：
```
git-release
```
,
```
api-design
```
,
```
frontend-testing
```

description - Skill的使用场景

1-1024个字符
包含用户实际会说的具体触发短语
明确说明使用场景
决定Agent是否加载该Skill

优秀的描述示例：

yaml

description: This skill should be used when the user asks to "create a database schema", "design SQL tables", "optimize queries", or needs guidance on relational database design.

糟糕的描述示例：

yaml

description: Helps with databases.  # 过于模糊，无触发短语

Optional Fields

可选字段

license - Legal terms (e.g., MIT, Apache-2.0)
compatibility - Target platform (e.g., opencode)
metadata - String-to-string map for custom fields

Unknown frontmatter fields are ignored.

license - 法律条款（如MIT、Apache-2.0）
compatibility - 目标平台（如opencode）
metadata - 自定义字段的键值对

未知的frontmatter字段会被忽略。

Progressive Disclosure Principle

渐进式披露原则

Skills use three-level loading to manage context efficiently:

Level 1: Metadata (always loaded)

Skill name and description
~50-100 words
Helps agents decide which skills to load

Level 2: SKILL.md body (loaded when triggered)

Core concepts and workflows
1,500-2,000 words ideal (<5,000 max)
Essential procedures and quick reference

Level 3: Bundled resources (loaded as needed)

references/ - Detailed documentation
examples/ - Working code samples
scripts/ - Utility tools (can execute without reading)

What goes where:

SKILL.md (always loaded when skill triggers):

Core concepts and overview
Essential procedures
Quick reference tables
Pointers to references/examples/scripts

references/ (loaded when agents need details):

Detailed patterns and techniques
Complete API documentation
Migration guides
Troubleshooting and edge cases

examples/ (loaded when agents need samples):

Complete working scripts
Configuration files
Templates

scripts/ (executed or loaded when needed):

Validation tools
Testing helpers
Automation scripts

For detailed strategy, see

references/progressive-disclosure.md

Skill采用三级加载机制，高效管理上下文：

级别1：元数据（始终加载）

Skill名称和描述
约50-100字
帮助Agent决定加载哪些Skill

级别2：SKILL.md正文（触发时加载）

核心概念和工作流
理想字数1500-2000字（最多不超过5000字）
核心流程和快速参考

级别3：捆绑资源（按需加载）

references/ - 详细文档
examples/ - 可运行代码示例
scripts/ - 实用工具（无需读取即可执行）

内容分配原则:

SKILL.md（Skill触发时始终加载）:

核心概念与概述
核心流程
快速参考表格
指向references/examples/scripts的链接

references/（Agent需要细节时加载）:

详细模式与技术
完整API文档
迁移指南
故障排除与边缘情况

examples/（Agent需要示例时加载）:

完整的可运行脚本
配置文件
模板

scripts/（需要时执行或加载）:

验证工具
测试辅助工具
自动化脚本

详细策略请参考

references/progressive-disclosure.md

。

Examples

示例

Study the bundled examples to see skills in action:

Minimal skill (

examples/minimal-skill/

)

Single SKILL.md file
Simple knowledge domain
No bundled resources

Standard skill (

examples/standard-skill/

) - Recommended

SKILL.md with core content
references/ for detailed documentation
Best for most use cases

Complete skill (

examples/complete-skill/

)

All features demonstrated
references/, examples/, scripts/
Shows full progressive disclosure

参考内置示例，了解Skill的实际应用：

最简Skill（

examples/minimal-skill/

）

仅包含SKILL.md文件
简单知识领域
无捆绑资源

标准Skill（

examples/standard-skill/

）- 推荐

包含核心内容的SKILL.md
用于详细文档的references/
适用于大多数场景

完整Skill（

examples/complete-skill/

）

展示所有功能
包含references/、examples/、scripts/
完整演示渐进式披露机制

Validation Script

验证脚本

Use the included validation script to check skill structure:

bash

undefined

使用内置验证脚本检查Skill结构：

bash

undefined

Validate a skill

验证Skill

.opencode/skills/skill-creation/scripts/validate-skill.sh path/to/skill

Example

示例

.opencode/skills/skill-creation/scripts/validate-skill.sh .opencode/skills/my-skill


The script checks:
- SKILL.md exists
- Valid YAML frontmatter
- Required fields present
- Name matches directory
- Name follows regex pattern
- Description length
- Referenced files exist

.opencode/skills/skill-creation/scripts/validate-skill.sh .opencode/skills/my-skill


脚本检查以下内容：
- SKILL.md是否存在
- YAML frontmatter是否有效
- 必填字段是否存在
- 名称是否与目录一致
- 名称是否符合正则格式
- 描述长度
- 引用的文件是否存在

Permissions

权限控制

Control which skills agents can access in

opencode.json

json

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

Permission levels:

```
allow
```
- Skill loads immediately
```
deny
```
- Skill hidden from agents
```
ask
```
- Prompt user before loading

Patterns support wildcards for flexible control.

在

opencode.json

中控制Agent可访问的Skill：

json

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

权限级别:

```
allow
```
- Skill立即加载
```
deny
```
- Skill对Agent隐藏
```
ask
```
- 加载前询问用户

支持通配符模式，实现灵活控制。

Troubleshooting

故障排除

Skill doesn't appear:

Verify SKILL.md is all caps
Check frontmatter has
```
name
```
and
```
description
```
Ensure skill name is unique across all locations
Check permissions in opencode.json

Skill loads but content is wrong:

Check YAML frontmatter syntax
Verify markdown starts after
```
---
```
closing
Review referenced file paths

Name validation fails:

Must be lowercase only
Use single hyphens (no consecutive
```
--
```
)
Cannot start/end with hyphen
Only alphanumeric and hyphens

Skill未显示:

确认SKILL.md为全大写文件名
检查frontmatter是否包含
```
name
```
和
```
description
```
确保Skill名称在所有位置中唯一
检查opencode.json中的权限设置

Skill加载但内容错误:

检查YAML frontmatter语法
确认Markdown内容在
```
---
```
结束标记之后
检查引用文件的路径

名称验证失败:

必须全小写
使用单个连字符（不能连续使用
```
--
```
）
不能以连字符开头或结尾
仅包含字母、数字和连字符

Best Practices

最佳实践

Core Principles

核心原则

Concise is key - Assume the LLM already has knowledge. Only add context the LLM doesn't have. Challenge each piece:

Does the LLM really need this explanation?
Can I assume the LLM knows this?
Does this paragraph justify its token cost?

Write in third person - Descriptions are injected into system prompts:

✓ Good: "Processes Excel files and generates reports"
✗ Avoid: "I can help you process Excel files" or "You can use this to..."

Set appropriate degrees of freedom:

High freedom (text-based instructions): Multiple approaches valid, context-dependent decisions
Medium freedom (pseudocode/templates): Preferred pattern exists, some variation acceptable
Low freedom (specific scripts): Operations fragile, consistency critical

Use consistent terminology - Choose one term and use throughout:

✓ Always "API endpoint", "field", "extract"
✗ Mix "API endpoint"/"URL"/"API route", "field"/"box"/"element"

简洁为上 - 假设LLM已具备基础常识，仅添加LLM不具备的上下文。对每部分内容提出质疑：

LLM真的需要这个解释吗？
我能否假设LLM已经知道这个？
这段内容的token成本是否合理？

使用第三人称 - 描述会被注入系统提示：

✓ 正确：「处理Excel文件并生成报告」
✗ 避免：「我可以帮你处理Excel文件」或「你可以用这个来...」

设置合适的自由度:

高自由度（基于文本的指令）：多种方法有效，需根据上下文决策
中自由度（伪代码/模板）：存在首选模式，允许一定变化
低自由度（特定脚本）：操作易出错，一致性至关重要

使用一致术语 - 选择一个术语并保持一致：

✓ 始终使用「API endpoint」「field」「extract」
✗ 混合使用「API endpoint」/「URL」/「API route」，「field」/「box」/「element」

DO

建议做法

Include specific trigger phrases in description (3-5 phrases users would actually say)
Keep SKILL.md focused (1,500-2,000 words, <5,000 max)
Use progressive disclosure for large skills
Write in imperative form ("Configure the setting" not "You should configure")
Write descriptions in third person
Provide working examples in examples/
Reference bundled resources clearly in "Additional Resources" section
Test with real use cases
Use forward slashes in file paths (not backslashes)
Keep references one level deep from SKILL.md
Add table of contents to reference files >100 lines
Use consistent terminology throughout

在描述中包含3-5个用户实际会说的具体触发短语
保持SKILL.md内容聚焦（1500-2000字，最多不超过5000字）
大型Skill使用渐进式披露机制
使用祈使句（「配置设置」而非「你应该配置设置」）
描述使用第三人称
在examples/中提供可运行示例
在「额外资源」章节清晰引用捆绑资源
使用真实场景测试
文件路径使用正斜杠（而非反斜杠）
引用文件与SKILL.md保持一级目录深度
超过100行的引用文件添加目录
全程使用一致术语

DON'T

避免做法

Use vague descriptions without trigger phrases
Put everything in SKILL.md (>3,000 words without references/)
Write in second person ("you should") or first person ("I can help")
Leave resources unreferenced
Skip validation before using
Create duplicate information across files
Include time-sensitive information (use "old patterns" sections instead)
Use Windows-style paths (backslashes)
Create deeply nested references (keep one level)
Offer too many options without a clear default

使用模糊描述，不包含触发短语
所有内容都放在SKILL.md中（超过3000字且无references/）
使用第二人称（「你应该」）或第一人称（「我可以帮你」）
资源未被引用
使用前跳过验证
在多个文件中重复信息
包含时效性信息（改用「旧模式」章节）
使用Windows风格路径（反斜杠）
创建深度嵌套的引用（保持一级目录）
提供过多选项却无明确默认值

Additional Resources

额外资源

Reference Files

参考文件

For complete specifications and strategies:

references/frontmatter-spec.md
- Complete YAML frontmatter specification
references/progressive-disclosure.md
- Deep dive on 3-level loading strategy
references/common-mistakes.md
- Anti-patterns and how to avoid them
references/best-practices-guide.md
- Comprehensive best practices from Claude documentation adapted for OpenCode

如需完整规范和策略，请查阅：

references/frontmatter-spec.md
- 完整YAML frontmatter规范
references/progressive-disclosure.md
- 三级加载策略深度解析
references/common-mistakes.md
- 反模式及避免方法
references/best-practices-guide.md
- 从Claude文档适配的OpenCode完整最佳实践

Example Skills

Skill示例

Study these working examples:

examples/minimal-skill/
- Simplest possible skill
examples/standard-skill/
- Recommended structure with references
examples/complete-skill/
- All features demonstrated

参考以下可运行示例：

examples/minimal-skill/
- 最简Skill示例
examples/standard-skill/
- 包含references/的推荐结构
examples/complete-skill/
- 展示所有功能

Validation Script

验证脚本

scripts/validate-skill.sh
- Automated skill structure checker

scripts/validate-skill.sh
- 自动化Skill结构检查工具

Quick Reference

快速参考

Minimal skill structure:

skill-name/
└── SKILL.md

Standard skill structure (recommended):

skill-name/
├── SKILL.md
└── references/
    └── detailed-guide.md

Complete skill structure:

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   └── working-example.sh
└── scripts/
    └── validate.sh

Frontmatter template:

yaml

---
name: skill-name
description: This skill should be used when the user asks to "trigger 1", "trigger 2", or needs specific guidance.
---

Validation command:

bash

.opencode/skills/skill-creation/scripts/validate-skill.sh path/to/skill

最简Skill结构:

skill-name/
└── SKILL.md

标准Skill结构（推荐）:

skill-name/
├── SKILL.md
└── references/
    └── detailed-guide.md

完整Skill结构:

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   └── working-example.sh
└── scripts/
    └── validate.sh

Frontmatter模板:

yaml

---
name: skill-name
description: This skill should be used when the user asks to "trigger 1", "trigger 2", or needs specific guidance.
---

验证命令:

bash

.opencode/skills/skill-creation/scripts/validate-skill.sh path/to/skill