OpenCode Skills 安装实战：从编写到团队自动化应用

最近我把 opencode 的 skills 机制从头到尾折腾了一遍从最初的安装试错、目录放不对导致技能不生效到后面能十分钟写一个顺手的小技能再到现在把团队里重复的提交流程直接交给它处理整个过程踩了不少坑也攒了不少可以直接拿来用的经验。这篇文章我会围绕 opencode skills 的安装使用案例展开把为什么这么装、怎么验证、SKILL.md 怎么写、第三方技能包怎么装以及各种奇奇怪怪的报错和排查方法一次讲透。不管你是刚开始接触 opencode还是已经能跑起来但总感觉 skills 时灵时不灵这篇都值得花十分钟读完。1. 项目概述opencode skills 到底解决了什么问题1.1 先搞明白 skill 是什么很多刚接触 opencode 的人第一反应是“这不就是个终端里的 AI 助手吗”然后就开始问它问题、让它改文件。真正让 opencode 和普通聊天工具有本质区别的其实是 skills 这套机制。你可以把 skill 理解成给 AI 预装的一套“工作 SOP”——它不只是一个提示词而是一个包含任务描述、执行步骤、约束条件、示例参考的完整文件包。在我实际使用中一个 skill 的本质就是一坨结构化的指令文件核心是 SKILL.md。这个文件决定了 AI 在什么场景下会被触发、触发之后要按什么流程干活、哪些事情不能做、输出格式长什么样。没有 skill 的时候你每次都要把“请你按我们团队的规范审查代码先看错误处理再看资源释放……”这串话重新敲一遍有了 skill 之后只要它识别到你正在做代码审查就会自动把这些约束全部带上完全不用重复劳动。我更喜欢用另一个类比普通对话相当于你请了一个实习生你得每次交代背景和要求装了 skill 就等于给这个实习生发了一本操作手册他拿到任务后会自己翻手册按固定流程执行。这也是为什么我会推荐所有重度使用 opencode 的人都好好研究一下 skills它省下的不只是输入时间更重要的是让你的 AI 输出质量稳定在某个水平线上。1.2 什么情况下才值得折腾 skills也不是所有场景都需要 skill。我自己的经验是当一件事满足“高频出现”“流程固定”“标准可描述”这三点时就很适合做成 skill。举个例子我们团队里每个合并请求在提交前都需要做一轮自查检查错误是否被吞掉、资源是否释放、日志是否打全、代码风格是否统一。以前我靠脑子记偶尔还会漏掉某个检查项。后来我把这套流程写成一个 skill每次提交前直接对着变更跑一遍AI 输出的检查清单和团队规范几乎一一对应省心很多。适合做成 skills 的任务常见的有代码审查、单元测试生成、提交信息撰写、项目脚手架生成、数据库查询优化、日志格式分析。相反如果是高度发散、每次要求都不同的任务比如“帮我聊聊这个架构设计”就不太适合固化成 skill因为它的判断标准和执行步骤没法稳定描述。如果你现在只用 opencode 做一些零散的问答skills 对你来说可能还不是刚需。但只要你开始处理重复性开发任务或者想把团队规范固化下来让每个成员都能自动遵守skills 就是那个性价比极高的入口。2. 安装前的环境准备让你的工具链一步到位2.1 运行环境与前置依赖在装 skills 之前先把 opencode 主程序装在干净的环境里。这步看起来基础但我在排查各种问题时发现很多“skill 装不上”“加载报错”的根源其实在主程序版本太旧、或者环境中缺少基础工具。opencoe 是一个命令行工具因此它需要运行在终端环境里。macOS 和主流 Linux 发行版是体验最好的如果用的是 Windows建议优先走 WSL 或者用 Git Bash 之类的环境避免文件路径和权限相关的坑。磁盘和内存没有特别夸张的要求普通开发机完全够用但如果你要同时加载多个大型 skill内存建议至少保证 4GB 可用空间。还有一个很重要的前置依赖是运行环境本身。opencode 构建在某个现代运行时之上所以在安装主程序之前我强烈建议先把环境里的运行时版本升到当前 LTS 及以上。版本太老会出现各种莫名其妙的兼容问题最典型的就是装完了能启动但一加载 skill 就报语法错误。提示如果你之前装过别的命令行 AI 工具尽量注意它们之间是否有配置目录冲突。我就遇到过两个工具共用同一个配置目录导致 skill 互相覆盖的情况排查了很久才发现是这种低级问题。2.2 安装 opencode 主程序的几种方式opencode 官方提供了好几种安装方式我分别试过包管理器安装、脚本安装和源码编译安装说一下区别。对于大部分用户最推荐的是用包管理器全局安装。打开终端执行一条命令就能装完比如我用过的npm install -g opencode如果你常用 Homebrew也可以直接用 brew 安装好处是后续升级、卸载会方便很多。具体命令我在这里不赘述因为不同的包管理器在不同系统上差异挺大你只需要知道一条原则选一个你本来就熟悉、每天都在用的包管理器就好。如果你不喜欢全局安装污染环境官方也提供了安装脚本这个方案适合想尝鲜但又不确定要不要长期使用的用户。它会自动下载一个可执行文件到你的用户目录下不会需要 root 权限也不干扰系统全局包。我用脚本装过一次整个过程大概几十秒之后启动速度和包管理器装的差别并不大。源码编译安装是最后的选择适合想改源码或者对性能极度敏感的人。这个方式需要手动拉取仓库、安装依赖、构建产物步骤相对繁琐除非你有具体理由否则我不建议在安装阶段就选它。从我实际测试来看包管理器和脚本安装完全足够日常使用了。2.3 刚装完怎么快速自检装完之后不要急着配 skills先跑一遍自检确认主程序本身是健康的。这个习惯能帮你省下后面大量的排查时间。先验证版本和帮助信息是否正常输出opencode --version opencode --help如果这两条命令能正常输出说明主程序基本可用。接下来看看配置目录是否创建成功。opencode 会在你的用户主目录下生成一个隐藏的配置目录你可以在终端里用以下命令确认ls -la ~/.config/opencode正常情况下应该能看到类似的目录结构如果没有先手动启动一次 opencode 让它生成默认配置。有些用户装了主程序后直接去创建 skills 目录结果发现根本不生效就是因为还没真正启动过、默认配置都没生成。3. skills 的核心机制目录、格式与触发逻辑3.1 技能文件到底该放哪里这是整个安装使用案例里最容易被忽略、也最容易导致失败的部分。skills 不是随便丢到哪里都可以被识别的它必须放在 opencode 指定的目录里。opencode 支持两种级别的 skills一种是全局技能对所有项目生效另一种是项目级技能只在当前项目目录下生效。全局技能一般放在用户配置目录下的 skills 子目录中比如前面提到的~/.config/opencode/skills这个目录下的每个子文件夹都代表一个独立的 skill。项目级技能则放在项目根目录下的.opencode/skills目录里适合存放和项目强绑定的专用流程。这里有一个很容易踩的坑不要在 skills 目录里直接放.md文件而是要建一个以技能名命名的文件夹然后在文件夹里放 SKILL.md。比如你做了一个叫code-review的技能正确的结构是~/.config/opencode/skills/code-review/SKILL.md而不是~/.config/opencode/skills/code-review.md我第一次就是在这个地方栽了跟头怎么加载都识别不到后来检查目录结构才发现文件层级放错了。opencode 在扫描技能时读的是每个子目录下的 SKILL.md直接在根目录放散装 Markdown 是不会有任何反应的。存放位置作用范围典型用途全局 skills 目录所有项目通用开发规范、代码审查、提交信息生成项目级 .opencode/skills当前项目项目专用构建流程、特定框架检查规则如果你发现 skill 在 A 项目里能生效、在 B 项目里失效了第一件事就是看看是不是把项目级技能和全局技能放混了。3.2 SKILL.md 到底怎么写SKILL.md 是技能的核心文件格式上其实很灵活但我在实践证明中总结了一套很稳的结构按这个写基本不会出兼容问题。文件最顶部是一段 YAML 格式的元信息用来描述技能的名称、用途和基本规则。核心字段有三种name 定义技能名description 描述什么时候触发rules 列出硬性约束。description 尤其重要因为 AI 是靠读它来判断“当前用户请求是否匹配这个技能”的。description 写得越具体触发准确率越高写得太泛就会出现你让它写测试代码结果它把代码审查技能也加载了的情况。YAML 元信息下面就是技能正文通常是一大段 Markdown包含执行步骤、输入输出说明、示例和注意事项。我建议正文里把“步骤”写成分步列表把“需要遵守的规则”单独列出来不要混在一起。AI 在生成回复时会把正文当作最重要的参考如果步骤和规则混成一大段文字它很可能遗漏某条关键约束。下面是我在用的一种比较标准的写法你可以在自己的技能里参考--- name: code-review description: 当用户请求审查代码变更、检查代码质量或提交前检查时使用主要面向错误处理、资源释放、性能和安全问题。 rules: - 必须逐个检查错误处理是否完善 - 必须检查资源是否释放 - 输出必须按严重程度排序 --- # Code Review Skill 当用户请求代码审查时按照以下步骤执行 1. 列出被审查的文件与变更范围 2. 逐个检查错误处理、资源释放、可读性、安全性 3. 对每个问题给出严重等级阻断、建议、可选 4. 最后输出汇总清单这里有个细节要注意rules 和正文里的步骤不要重复太多。rules 是“必须遵守的底线”正文是“具体执行流程”。两者侧重点不同AI 读起来也更清楚。3.3 触发机制与匹配逻辑装好了技能你肯定会好奇一个问题它是怎么被触发的我自己把触发方式总结为两种自动匹配和手动唤起。自动匹配是最常用的方式。opencode 在你和 AI 对话时会拿用户的请求内容和每个技能的 description 做语义匹配。比如你问“帮我看看这块代码有什么问题”如果存在一个 description 为“代码审查”的技能AI 就大概率会自动加载它。这个过程你甚至感觉不到但它的确影响了最终输出的风格和结构。手动唤起则更像一个命令面板。你可以在对话中输入类似/skills的指令然后看到当前可用的技能列表再主动选择指定技能。这种方式适合那些你明确知道要跑什么流程、但 AI 没有自动识别到的场景。从我的测试经验来看自动匹配的准确率受两个因素影响最大description 里是否包含用户请求中的核心措辞以及技能正文是否有足够明确的执行信号。如果你发现某个技能老是自动触发失败不要急着怀疑主程序的 bug先回去看 description把它改得更像用户真实会说的话比如加上“检查”“审查”“review”“重构”这类高频关键词。另外也要注意opencode 的会话是分上下文的。你在这个会话里加载过的技能不会自动带进另一个新会话。每次新会话开始时AI 都会重新做一次技能匹配所以如果你换了目录、改了 skill 文件但觉得“没生效”很可能是旧会话缓存导致的重启一个会话再试往往就好了。4. 实操案例一从零手写一个代码审查 skill4.1 设计前先想清楚要约束什么纸上谈兵了这么久下面直接来一个完整的实操案例。我选“代码审查”作为案例是因为它覆盖了 skill 设计里几乎所有关键点规则制定、触发描述、输出格式约束而且每个开发者都听得懂。设计 skill 之前我先花了几分钟想清楚一个问题我希望 AI 在审查代码时到底按什么标准来做这个标准必须写下来不能靠 AI 自由发挥。以我手头这个项目为例最关心的四件事是错误处理有没有做全、资源有没有释放、有没有明显的性能浪费、有没有安全问题。于是我给这个 skill 定了几条核心规则。第一条错误处理方面要求 AI 逐个检查异常分支是否被捕获不能被静默吞掉。第二条资源释放方面要求检查文件句柄、网络连接、数据库连接等是否都有对应的关闭逻辑。第三条性能方面重点看循环里有没有重复查询、有没有不必要的大对象复制。第四条安全问题比如 SQL 拼接、命令注入、硬编码密钥这类必须高亮标出。设计完成之后我心里大概有了一个标准输出模板每个问题都要有严重等级、文件位置、问题描述和修改建议。这个模板也让后面的 SKILL.md 写起来有了明确靶子。4.2 从零编写 SKILL.md设计定完直接创建目录结构。我打算把这个技能放到全局目录让所有项目都能共用所以先执行mkdir -p ~/.config/opencode/skills/code-review然后在这个目录下新建 SKILL.md写入设计好的元信息和执行步骤。为了让输出更稳定我还在正文里加了一段“示例输出格式”告诉 AI 审查结果必须按阻断、建议、可选三个等级分组展示。下面是这个技能的完整内容你可以直接复制改成自己的版本--- name: code-review description: 当用户请求代码审查、代码检查、提交前 self-review、或让 AI 找出代码中的错误处理、性能、安全问题时触发。 rules: - 必须检查异常分支是否被处理禁止吞掉错误 - 必须检查文件、网络、数据库连接等资源是否释放 - 必须检查 SQL 拼接、命令注入、硬编码密钥等安全问题 - 输出必须分为阻断级、建议级、可选级三类 --- # Code Review Skill ## 执行步骤 1. 先查看当前变更文件列表确认审查范围 2. 对每个文件做静态检查关注错误处理、资源释放、性能和安全性 3. 按严重程度输出问题清单 ## 输出格式 ### 阻断问题 问题位置、问题描述、修改建议 ### 建议问题 问题位置、问题描述、修改建议 ### 可选问题 问题位置、问题描述、修改建议写完文件之后我习惯顺手检查一遍 YAML 格式因为这里特别容易出低级错误。最常见的坑是 description 里用了英文冒号:而 YAML 会把冒号当成键值分隔符导致解析失败。解决办法是把冒号改成中文冒号或者给整个值加上引号。宁可多花一分钟检查也不要装好了才发现加载失败。4.3 安装并实测一份代码写好 SKILL.md 后保存文件并重新启动 opencode 会话让主程序重新扫描技能目录。然后我找了一段有明显问题的代码作为测试对象def get_user_data(user_id): conn create_connection() result conn.execute(fSELECT * FROM users WHERE id {user_id}) return result.fetchone()这个函数有很多明显问题只进不出没有关闭连接、存在 SQL 注入、没有处理异常。正常情况下AI 应该直接触发 code-review 技能然后给出分级审查结果。我实测下来的输出基本符合预期它把 SQL 注入标记为阻断级问题把连接未关闭标记为阻断级问题并给出了对应的修改建议。这里有个很好的例子说明 skill 的真正价值如果没有这个技能AI 虽然也能指出 SQL 注入问题但它的输出是随机的这次可能先讲注入、下次可能先讲连接泄漏而且格式每次都不一样。有了技能之后它每次都会按同样的模板、同样的优先级顺序来输出这对团队协作非常重要因为人工 review 的时候不用再重新适应一套新格式。4.4 效果调整记录不过我实测也发现了一个问题初始版本的技能会过于严格它把“未使用类型标注”这种非常主观的风格问题也列进了建议级这其实偏离了我的原始需求。我原本只关注错误处理、资源、性能和安全风格问题不应该由这个技能来管。于是我回到 SKILL.md在 rules 里加了一条“只关注运行时正确性和安全性不输出代码风格建议”然后再重新测试。这一轮输出干净了很多只保留了真正的硬性问题。这个“测试-反馈-修正”的循环其实是 skill 开发里最核心的工作方式不要指望第一版就完美每个技能都应该在使用中不断校准。我还给这个技能加了一个小扩展输出里自动附上“当前优先处理阻断级问题”的提示语这样 AI 生成的内容就不会让开发者被一堆琐碎问题淹没而是聚焦在最该修的地方。5. 实操案例二第三方 skills 的安装与使用5.1 去哪找现成的技能包自己写 skill 很有意思但有的时候你的需求别人早就做过了直接安装现成的能省下大量时间。第三方 skills 的获取渠道其实很分散我常用的有两个方向一是在代码托管平台上搜索“opencode skills”相关的合集仓库二是在技术社区或官方讨论区里翻别人分享的技能配置。搜索的时候有个技巧不要只搜“skills”更精确的关键词是“SKILL.md”或者“opencode skills collection”这样能命中那些真正把技能做成可安装结构的项目。很多文章里提到的“技能”其实只是贴了一段提示词让大家自己复制那种不是我要找的。我想找的是目录结构完整、SKILL.md 已经写好的现成安装包。我目前用得最多的一个第三方技能是测试用例生成相关的。它内置了多种测试框架的模板能根据你的代码自动生成对应的测试文件。这个技能自己写的话至少要花半天直接安装只用了两分钟性价比很高。5.2 完整安装过程示范这里以安装一个第三方的“测试生成”技能为例带你走一遍完整的安装过程。先用 git 把整个技能仓库克隆到临时目录git clone 某个技能仓库地址 /tmp/skills-repo克隆完成后先别急着复制我先看一下仓库结构。这一步很关键因为不同作者维护的仓库结构差异很大有的直接把所有技能放在根目录有的放在子目录里。如果盲目复制很容易出现把仓库里的说明文档当成技能目录复制过去的情况。进入仓库目录后执行ls -la我习惯用树形结构看一眼有哪些技能文件夹find . -name SKILL.md这条命令会列出仓库里所有的 SKILL.md 文件。如果一个文件夹下有 SKILL.md那大概率就是可以安装的技能如果没有那很可能是项目源文件或者说明文档不要整个复制进去。确认好目标技能后把它整体复制到全局 skills 目录cp -r /tmp/skills-repo/test-generator ~/.config/opencode/skills/复制完成后重新启动 opencode然后输入/skills手动打开技能列表如果能看到你刚安装的技能名就说明已经生效了。5.3 真实使用感受与注意事项这次安装第三方技能的过程整体很顺利但我也发现了一些值得注意的细节。首先第三方技能的稳定性参差不齐。有些作者的 SKILL.md 写得很粗糙rules 和正文几乎没有任何实质约束AI 加载之后输出的内容跟没装差不多。遇到这种情况我一般会做一次“本地化适配”把它当作自己写的技能一样去修改 description 和 rules而不是期望原样就能用。其次有些技能会在 SKILL.md 里引用外部的脚本文件或者命令行工具比如某些技能会写“先执行xxx命令来收集项目信息”。如果你本地没装对应工具这个技能就会在第一步就卡住。所以每次装完第三方技能后我会先打开 SKILL.md 扫一眼确认有没有外部依赖。最后还要留意技能之间的相互影响。如果你同时启用了 code-review 和 test-generator 两个技能而两者的 description 都写了“检查代码质量”那么在对话里可能会同时触发两个技能导致输出混合。解决办法是让每个技能的 description 更专一避免语义空间重叠。6. 常见问题与排查技巧实录6.1 skill 既不显示也不触发这个问题我在各种群里看到太多人问过。如果你把技能放好了、SKILL.md 也写了但/skills列表里根本没有它或者 AI 怎么都不触发它优先检查以下三个层面。第一个层面是目录结构。确认你的技能是不是“skills 目录下一个独立文件夹里的 SKILL.md”不要直接放散文件也不要多套一层无关目录。第二个层面是配置文件权限。如果你用的是~/.config/opencode/skills确认当前用户有没有对这个目录的读权限权限不对会导致扫描时直接跳过。第三个层面是会话缓存。有时候文件没变但旧会话里还记录着旧的技能列表重开一个会话再试。我自己最常踩的是第二层尤其在一台 Linux 服务器上我之前用 sudo 创建了目录导致普通用户没有访问权限技能始终加载不出来。后来把目录 owner 改回当前用户就解决了。chown -R $(whoami) ~/.config/opencode6.2 YAML 格式问题导致加载失败YAML 格式错误是 SKILL.md 写完后最隐蔽的问题。它不像代码报错那么明显很多时候 opencode 只是静默地跳过这个技能也不会给出明显警告导致你疯狂检查目录结构却毫无收获。最常见的 YAML 错误有几种一是 description 或者规则文本里出现了英文冒号后跟空格YAML 会理解为这是一个新层级二是文本里用了制表符而不是空格缩进三是在字符串里用了特殊字符但没加引号。我的习惯是每次写完 SKILL.md 都先把 YAML 部分单独粘贴到一个在线校验工具里跑一遍确认没有语法错误再放入 skills 目录。另外注意 description 不要太长。我最初写 description 特别喜欢写一大长串描述结果不仅触发慢还偶尔导致 YAML 解析错乱。后来我控制在 100 字以内用最精简的语言描述触发场景效果好很多。6.3 技能脚本依赖缺失很多高级技能的正文里会包含命令调用比如让 AI 运行测试、编译代码、读取日志文件分析。这类技能对当前环境有明确要求如果你的开发机上没有对应工具AI 执行到某一步就会卡住。排查思路很简单打开 SKILL.md搜索所有反引号包裹的命令或者“运行”“执行”“调用”这类关键词然后把列出的工具逐个确认是否安装。我之前装过一个项目脚手架生成技能它内部调用了某个模板引擎我没装导致每次执行到一半就失败。装好依赖后立刻恢复正常。还有一个容易被忽视的点技能里写的命令路径是绝对路径还是相对路径。如果作者写的是个人机器的绝对路径比如/home/username/bin/xxx那到了你机器上就必然失效。遇到这种情况把路径改成通用命令名或者直接删掉该步骤。6.4 同名冲突与路径空格等坑如果你全局目录和项目目录各有一个同名技能opencode 会优先加载项目级技能这是我在实践里验证过的行为。但问题是很多人并不知道自己项目里藏着一个同名技能导致怎么改全局技能都没反应。排查方法很简单在你项目根目录执行find . -path *.opencode/skills* -name SKILL.md看看有没有项目级技能和全局技能重名。如果有要么改项目技能的名称要么删除一个。路径里的空格和特殊字符也需要注意。有些人的开发机用户目录包含空格比如/Users/My Name/.config/opencode/skills这种情况下如果某个技能脚本里硬编码了带空格的路径AI 在拼接命令时就容易出错。我的建议是遇到空格路径要么处理好转义要么干脆把技能文件放到一个不含空格的路径下省得给自己找麻烦。7. 一点经验和后续思路折腾完这一整套 skills 安装和使用的案例之后我最大的体会是skills 的真正价值不在“给 AI 加一段提示词”而在于把团队里那些隐性的工作标准和判断逻辑显性化了。以前新人接手代码审查完全靠问、靠猜、靠前辈嘴对嘴传现在只要装好同一个 skill大家审查出来的问题框架基本一致效率提升是实打实的。我个人建议如果你现在还没用过 skills不要一开始就想写一个万能技能。先挑一个最最日常、最最重复的小场景比如“帮我写规范的 git commit message”然后做一个最简单的技能跑通“编写-安装-触发-调整”这个闭环。等熟悉了再慢慢扩展更复杂的场景。后面如果你想在这套机制上继续深入还可以研究几个方向一是把技能和具体的命令行流程做深度绑定让它不只是输出建议而是直接帮你执行命令、创建文件二是根据不用项目自动激活不同的技能集三是在团队里把 skills 目录看成一个内部工具仓库用版本管理来维护技能迭代。技能文件本身就是代码——趁现在你手头的项目还不复杂赶紧把第一个 skill 建起来用多了就知道这东西有多顺手了。