OpenCode Skills 使用教程在 AI 辅助编程中你是否反复输入同样的提示词OpenCode 代理技能Skills正是为解决这一问题而生。开发者可以将高频工作流程、编码规范、专项操作指令等内容封装为独立技能文件代理通过内置skill工具按需加载无需重复编写提示词有效统一团队开发流程。技能体系支持项目级与全局级两种部署模式同时兼容 Claude Code、传统 Agents 目录格式对于跨工具迁移的用户十分友好。本文将系统讲解技能文件的存放规则、编写规范、调用方式、权限管控、功能禁用以及故障排查并搭配实战案例帮助开发者搭建可复用的技能体系。一、代理技能核心概述代理技能以SKILL.md作为核心载体遵循一个技能对应独立文件夹的规则。OpenCode 会自动扫描指定目录下的技能文件代理在执行任务时可主动发现并按需加载技能内容。核心价值指令复用将通用提示词、操作流程封装为技能告别重复输入流程标准化团队统一技能内容保证所有成员使用一致的开发规范按需加载技能不会常驻会话上下文仅在需要时加载降低资源消耗多端兼容原生目录兼容 Claude Code、旧版 Agents 目录迁移无成本。二、技能文件存放路径与检索规则OpenCode 会按照固定路径扫描技能文件分为项目级仅当前项目生效和全局级本机所有项目生效同时区分原生路径与兼容路径。所有路径均要求每个技能单独创建文件夹文件夹名称与技能名称保持一致文件夹内放置SKILL.md文件。2.1 全路径清单类型分类目录路径生效范围项目级OpenCode 原生.opencode/skills/技能名/SKILL.md当前 Git 仓库项目项目级Claude 兼容.claude/skills/技能名/SKILL.md当前 Git 仓库项目项目级旧代理兼容.agents/skills/技能名/SKILL.md当前 Git 仓库项目全局级OpenCode 原生~/.config/opencode/skills/技能名/SKILL.md本机所有项目全局级Claude 兼容~/.claude/skills/技能名/SKILL.md本机所有项目全局级旧代理兼容~/.agents/skills/技能名/SKILL.md本机所有项目2.2 目录检索逻辑项目级技能检索OpenCode 从当前工作目录开始向上遍历至 Git 仓库根目录沿途加载所有合法技能超出 Git 仓库范围后停止检索。全局级技能检索固定扫描全局目录本机任意 OpenCode 会话均可加载全局技能。优先级项目级技能优先级高于全局级技能同名技能会以项目内版本为准。三、[SKILL.md](SKILL.md) 编写规范SKILL.md文件由YAML Frontmatter头部元数据和正文指令内容两部分组成。OpenCode 仅识别规定的 Frontmatter 字段未知字段会自动忽略。3.1 Frontmatter 字段说明3.1.1 必填字段name技能名称有严格格式约束长度限制1 ~ 64 个字符字符规则仅支持小写字母、数字可使用单个连字符分隔格式要求不能以连字符开头、结尾不允许连续连字符绑定规则必须和技能所在文件夹名称完全一致校验正则^[a-z0-9](-[a-z0-9])*$。description技能描述长度限制 1 ~ 1024 字符。描述内容需精准具体便于代理判断调用时机。3.1.2 可选字段license技能开源协议例如MIT、Apache-2.0compatibility兼容工具标识例如opencode、claudemetadata自定义元数据采用字符串键值对格式可标注使用人群、工作流等附加信息。3.2 完整编写示例示例文件路径.opencode/skills/git-release/SKILL.md--- name: git-release description: 基于合并的PR生成更新日志建议版本号并提供gh发布命令 license: MIT compatibility: opencode metadata: audience: 项目维护者 workflow: github --- ## 技能使用场景 当需要对代码仓库进行版本打标、正式发布时使用本技能。若版本规则不明确请主动向用户确认。 ## 执行步骤 1. 读取近期合并的 PR 记录自动整理版本更新日志 2. 根据迭代内容给出合理的版本号升级建议 3. 生成可直接复制执行的 gh release 发布命令。3.3 正文编写建议明确使用场景标注技能适用的业务与操作场景拆解执行步骤按顺序划分操作流程引导代理分步执行补充约束规则添加异常处理、交互要求等限制条件。四、技能调用机制4.1 技能自动发现OpenCode 启动后会自动扫描所有合法目录汇总全部可用技能。技能的名称与描述会被整合到skill工具的内置描述中格式示例如下available_skillsskillnamegit-release/namedescription基于合并的PR生成更新日志建议版本号并提供gh发布命令/description/skill/available_skills4.2 代理调用语法代理识别需求后会通过标准语法调用指定技能skill({name:git-release})调用分为两种形式代理根据需求自动调用或接收用户指令后间接触发。五、技能全局权限配置通过项目根目录opencode.json文件的skill节点可统一管控全代理的技能访问权限支持精准匹配与通配符匹配。5.1 权限动作说明权限值执行行为allow直接加载技能无需人工审批deny对代理隐藏该技能完全禁止访问ask加载前弹出审批窗口确认后方可使用5.2 全局权限配置示例配置支持*通配符批量管理技能遵循后匹配规则优先原则{$schema:https://opencode.ai/config.json,permission:{skill:{*:allow,pr-review:allow,internal-*:deny,experimental-*:ask}}}配置解读默认放行所有技能单独允许代码评审技能禁止所有内部技能所有实验类技能使用前需人工审批。六、按代理单独覆写技能权限当不同代理需要差异化权限时可单独配置代理专属规则代理权限优先级高于全局权限。分为自定义代理、内置代理两种配置方式。6.1 自定义代理配置在自定义代理的.md配置文件 Frontmatter 中设置技能权限文件路径参考~/.config/opencode/agents/--- description: 代码评审专用子代理 mode: subagent permission: skill: documents-*: allow --- # 代理指令正文 专注代码评审工作优先使用文档类技能。6.2 内置代理配置在opencode.json的agent节点中为官方内置代理配置权限{$schema:https://opencode.ai/config.json,agent:{plan:{permission:{skill:{internal-*:allow}}}}}七、完全禁用技能功能对于纯检索、纯分析类专用代理可直接关闭skill工具。禁用后技能列表会从工具描述中移除。7.1 自定义代理禁用配置--- description: 代码检索只读代理 mode: subagent tools: skill: false --- # 代理指令正文 仅负责检索代码不使用任何技能。7.2 内置代理禁用配置{$schema:https://opencode.ai/config.json,agent:{plan:{tools:{skill:false}}}}八、常见问题排查技能无法展示时首先检查文件名技能主文件必须为大写SKILL.md大小写错误会导致系统无法识别。校验 Frontmatter 完整性name和description为必填字段缺失任意一个都会造成技能加载失败。保证技能名称唯一同一检索范围内所有技能名称不能重复名称冲突会引发加载异常。排查权限拦截若技能被deny规则匹配会对代理完全隐藏需核对全局权限、代理专属权限配置。检查目录结构禁止将SKILL.md直接放在skills根目录必须遵循「独立文件夹 内部 [SKILL.md](SKILL.md)」的结构。确认检索范围项目级技能仅在当前 Git 仓库内生效切换仓库后无法读取原有项目技能。九、实战技能案例案例 1项目级代码评审技能文件路径.opencode/skills/code-review/SKILL.md--- name: code-review description: 对代码进行规范检查、漏洞扫描并输出评审报告 license: MIT --- ## 代码评审规则 1. 检查代码是否符合项目 ESLint Prettier 规范 2. 排查接口权限、参数校验、依赖引入等安全漏洞 3. 分析代码性能问题给出优化建议 4. 仅输出评审结果不自动修改代码。案例 2全局单元测试编写技能文件路径~/.config/opencode/skills/unit-test/SKILL.md--- name: unit-test description: 基于现有代码编写标准单元测试 compatibility: opencode --- ## 执行要求 1. 分析目标函数的入参、出参与业务逻辑 2. 覆盖正常、边界、异常三类测试场景 3. 使用项目默认测试框架编写代码并补充注释。案例 3Git 提交规范技能文件路径.opencode/skills/git-commit/SKILL.md--- name: git-commit description: 按照约定式提交规范生成 commit 信息 --- ## 提交规范 提交格式类型(模块): 描述 类型包含feat、fix、docs、style、refactor、test、chore。 根据代码改动内容生成合规的 Git 提交文案。十、总结OpenCode Skills 以SKILL.md为核心文件搭配多层目录结构、精细化权限体系实现指令的模块化复用。项目级技能适配单项目专属流程全局技能服务多项目通用规范同时兼容多款主流工具降低迁移成本。在实际使用中务必遵守文件命名、目录结构、Frontmatter 等基础规范避免技能加载异常结合权限规则区分不同代理的使用范围高危技能可设置审批机制提升安全性。针对专用代理可直接关闭技能功能精简代理能力边界。合理运用技能体系能够大幅减少重复提示词编写工作统一团队开发标准充分提升 OpenCode 的使用效率。