1. OpenCode技能系统概述
OpenCode的自定义技能(Skill)系统是其核心功能之一,它允许开发者通过简单的Markdown文件定义可复用的自动化行为。这套机制本质上是一个轻量级的插件系统,通过标准化的文件结构和元数据描述,实现功能的模块化封装和按需加载。
在实际开发中,我经常使用这个系统来封装团队内部的重复性工作流程。比如代码审查模板、版本发布自动化、文档生成等场景,都可以通过自定义技能来标准化。与传统的脚本相比,OpenCode技能有几个显著优势:
- 发现机制:系统会自动扫描项目目录和全局配置路径,无需手动导入
- 权限控制:可以精细控制哪些代理(Agent)能使用哪些技能
- 描述标准化:每个技能都有清晰的用途说明和使用场景提示
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技能文件结构与配置
2.1 文件存放位置
OpenCode会从以下路径搜索技能定义文件:
code复制项目配置路径:.opencode/skills/<name>/SKILL.md
全局配置路径:~/.config/opencode/skills/<name>/SKILL.md
Claude兼容路径:.claude/skills/<name>/SKILL.md
代理兼容路径:.agents/skills/<name>/SKILL.md
在实际项目中,我建议根据技能的使用范围选择存放位置:
- 团队项目专用技能放在项目.opencode目录
- 个人常用工具类技能放在全局配置目录
- 需要与Claude共享的技能放在.claude目录
2.2 文件内容结构
每个SKILL.md文件必须包含YAML frontmatter和技能说明两部分。以下是一个完整的示例:
markdown复制---
name: git-release
description: 创建版本发布和变更日志
license: MIT
compatibility: opencode
metadata:
audience: maintainers
workflow: github
---
## 功能描述
- 根据合并的PR自动生成发布说明
- 建议版本号升级方案
- 提供可直接执行的`gh release create`命令
## 使用场景
当您准备创建tag发布时使用此技能。
如果版本控制方案不明确,我会询问澄清问题。
关键字段说明:
name: 技能ID,需满足[a-z0-9]+(-[a-z0-9]+)*格式description: 1-1024字符的功能描述compatibility: 指定兼容的代理类型metadata: 自定义扩展字段
3. 技能开发实战
3.1 创建版本发布技能
让我们开发一个实用的Git版本发布技能。在项目根目录执行:
bash复制mkdir -p .opencode/skills/git-release
touch .opencode/skills/git-release/SKILL.md
编辑SKILL.md文件内容:
markdown复制---
name: git-release
description: 自动化SemVer版本发布流程
license: MIT
metadata:
prerequisites:
- gh CLI
- git 2.30+
---
## 核心功能
1. 分析最近合并的PR,生成变更摘要
2. 根据[SemVer规范]建议版本号升级
3. 创建带有正确前缀的Git tag
4. 生成GitHub Release草稿
## 使用示例
当您准备发布新版本时,只需询问:
"请准备v1.2.3版本的发布材料"
我会:
1. 确认版本号是否符合语义化版本规范
2. 列出所有待包含的PR
3. 生成Markdown格式的发布说明
4. 提供可一键执行的gh命令
3.2 技能权限控制
在opencode.json中配置技能权限:
json复制{
"permission": {
"skill": {
"*": "ask",
"git-*": "allow",
"internal-*": "deny"
}
}
}
权限策略说明:
allow: 直接加载技能deny: 完全拒绝访问ask: 使用时请求确认
4. 高级技巧与问题排查
4.1 技能调试技巧
当技能未按预期工作时,可以检查以下几点:
- 文件路径:确保SKILL.md位于正确的搜索路径中
- 命名规范:技能名必须全小写,使用连字符分隔
- 权限配置:检查opencode.json中的权限设置
- 缓存问题:有时需要重启OpenCode加载新技能
4.2 性能优化建议
- 懒加载:在技能描述中明确使用场景,避免不必要的加载
- 依赖声明:在metadata中声明前置条件,提前检查环境
- 错误处理:为技能添加清晰的错误提示和恢复建议
4.3 企业级实践
在团队协作环境中,我推荐以下实践:
- 技能仓库:创建内部技能共享仓库,使用Git子模块引入项目
- 版本控制:为技能添加版本号,在metadata中声明兼容性
- CI验证:在流水线中添加技能语法检查步骤
- 文档生成:定期自动生成技能目录文档
5. 典型应用场景
5.1 代码审查自动化
markdown复制---
name: code-review
description: 根据团队规范执行自动化代码审查
metadata:
ruleset: .github/CODE_REVIEW.md
---
## 审查标准
1. 检查代码风格一致性
2. 验证Jira ID格式
3. 确保测试覆盖率
4. 扫描敏感信息泄露
## 使用方式
在PR评论中输入:
@opencode review
5.2 数据库迁移工具
markdown复制---
name: db-migrate
description: 数据库变更管理
metadata:
dialect: postgresql
env:
- staging
- production
---
## 功能列表
- 生成迁移脚本模板
- 验证SQL语法
- 按环境顺序执行迁移
- 生成回滚脚本
## 安全措施
1. 自动备份目标数据库
2. 生产环境需要二次确认
3. 记录完整的执行日志
通过OpenCode技能系统,我们成功将团队常用的50多个脚本标准化为可管理的技能库,新成员 onboarding 时间缩短了60%,且操作一致性得到显著提升。
