最近在终端里把OpenCode用起来了说实话越用越觉得它跟IDE里那些AI插件完全是两种东西。它不是聊天窗口也不是补全工具而是直接趴在你的命令行里能读仓库、改代码、跑命令、提交PR的那种agent。但用得多了我发现自己一直在重复干同一件事每次起一个新会话都要把项目的代码规范、输出格式、注意事项一字一句再交代一遍。后来把OpenCode的技能系统研究了一下用基础技能模板把常用的工作方式固化下来整个效率直接上了一个台阶。这篇文章就围绕OpenCode技能系统的基础部分展开重点讲讲基础技能模板长什么样、怎么从零写一个、放哪儿才能被正确加载以及我在安装配置和实际使用中踩过的一堆坑。内容对刚接触OpenCode的人友好也能给已经在用的人一点整理技能库的思路。如果你是那种希望AI助手按你的规矩干活、而不是每次自由发挥的人这篇应该能给你省下不少时间。1. 为什么OpenCode需要一个技能系统1.1 OpenCode是什么和IDE里的AI编程工具有什么区别OpenCode是一个开源终端AI编程助手核心逻辑很简单在命令行里启动它它会读取你当前目录的项目结构、打开的git状态、选中的文件内容然后根据你的指令去理解代码库、修改文件、执行命令。它和Copilot、Cursor这类产品的最大不同是它默认就是一个agent工作流不是“你写一行它补一行”而是“你给它一个目标它自己规划步骤、动手改代码、跑测试验证”。这带来的结果是OpenCode的输出强烈依赖上下文。你在终端里起的每个会话就好像给一个能力很强但记性很差的外包工程师派活。第一次配合你得把项目背景说清楚第二次换个会话它又忘了。这一点刚开始用的时候很让人抓狂后来才发现官方的解法就是技能系统。1.2 技能系统解决的是“每次重新教一遍”的问题技能系统的本质是把一段可复用的指令、规范或工作流打包成一个独立模块OpenCode在合适的时候自动加载它。你可以把它理解成给AI助手建SOP。比如你的团队要求PR描述必须包含测试记录和影响范围你不用每次都在对话里写一遍只要做一个技能OpenCode识别到相关需求时就会自动把规则注入上下文。我自己用下来技能系统最有价值的场景有三个。第一是项目规范类比如提交信息怎么写、代码风格怎么控制。第二是重复任务类比如每次发版本都要做的那套检查清单。第三是方法论类比如代码审查应该按什么顺序、重点看哪几类问题。这些内容有一个共同特点确定性高、可复用、而且自由发挥的空间越小越好。1.3 基础技能模板在整套体系里的定位理解了技能是什么再说模板。模板不是某个具体技能而是一个可复用的骨架它定义了技能目录的结构、SKILL.md文件的格式、元数据怎么写、正文怎么组织。你每次新建一个技能不需要从零开始想格式套模板改内容就行。这也是我觉得OpenCode技能系统设计得比较舒服的地方它把“技能”本身做成了一种标准化的文件结构而不是靠对话里的临时指令。基础技能模板就是这套标准化的起点。把模板吃透后面无论是做代码审查技能、项目初始化技能还是运维检查技能都是同样的套路只是内容不同。本文后面讲的实操就是把这套套路完整走一遍。2. 基础技能模板的结构与编写规范2.1 技能目录的存放位置与命名规则OpenCode的技能一般放在专门的技能目录下既有全局目录也有项目级目录。全局目录作用于你机器上的所有项目适合放那些跟具体业务无关的技能比如通用的代码审查模板、git提交规范。项目级目录则跟随仓库走适合放跟这个项目强相关的规则比如这个项目特有的架构约束、测试要求。目录命名上建议全部用小写字母加连字符不要用空格和驼峰。原因有两个一是技能目录名通常会出现在加载路径里带空格很容易在解析时出幺蛾子二是模型在判定是否调用技能时会参考目录名和技能名称简短明确的连字符命名比驼峰更容易被准确识别。我见过有人把技能目录命名为Code Review Helper结果OpenCode的加载器在扫描时处理得很别扭改成code-review-helper之后一切正常。2.2 SKILL.md的格式拆解每个技能目录的核心文件是SKILL.md。这个文件的命名是固定的OpenCode扫描技能目录时就是靠这个文件名来识别一个技能是否存在。换句话说你可以把技能目录理解成一个包SKILL.md就是这个包的清单文件技能的描述、入口、逻辑全在这一个文件里。SKILL.md的结构分两部分开头的YAML frontmatter和正文。frontmatter用两组---包起来里面至少有name和description两个字段。name是技能的唯一标识description则是给模型看的“说明书”写清楚这个技能在什么情况下应该被触发。正文部分是技能的核心指令一旦技能被触发这一整段内容会作为系统指令的一部分注入到当前会话里。这里有个容易忽略的点description的质量直接决定技能能不能被正确触发。OpenCode不会在你每次对话时都把全部技能加载进来它会让模型根据你的指令和技能描述做匹配。如果描述写得太泛比如“处理代码相关任务”模型什么都想用写得太窄模型又想不起来用它。描述里最好包含触发场景、适用对象和边界三个要素。2.3 一个可直接抄作业的基础模板直接给一个最基础的模板大家看完就有谱了。新建一个目录比如~/.config/opencode/skills/basic-review/在里面创建SKILL.md内容如下--- name: basic-review description: 当用户要求进行代码审查、代码走查、代码复查、质量评估等任务时使用。适用于检查代码逻辑、潜在缺陷、可读性和项目规范符合度。 --- # 代码审查基础技能 你是一名严谨的资深代码审查专家。收到代码后请按以下步骤执行 1. 先梳理代码的输入、输出和核心逻辑用两三句话概括这段代码做了什么事。 2. 检查潜在缺陷空指针、越界、异常未捕获、并发问题、资源泄漏等。 3. 检查可读性命名是否达意、函数是否过长、逻辑是否有混淆点。 4. 对照项目规范缩进、引号风格、注释语言、git提交规范。 5. 输出审查结论按严重程度分为阻塞、建议、nit三个等级每条必须标注文件路径和行号。 ## 注意事项 - 不要为通过而通过宁可漏报也不编造问题。 - 所有修改建议必须给出具体改动思路禁止只说“建议优化”这类空话。 - 如果代码量超过500行优先审查核心路径和变更部分不要平均用力。这个模板麻雀虽小但已经把技能该有的要素都覆盖了触发条件、角色设定、执行步骤、输出规范、边界约束。熟练以后可以直接作为底稿扩展。3. 从模板到可用技能完整实操记录3.1 需求拆解先回答四个问题我不建议上来就闷头写SKILL.md。写技能之前先花几分钟把需求想清楚可以问自己四个问题。第一个问题这个技能在什么场景下被触发回答要具体到动作比如“用户要求生成commit message”而不是“提高代码质量”。第二个问题技能执行后要产出什么是一个文本列表、一份修改后的代码还是一个报告第三个问题技能需要哪些边界约束比如只处理前端文件、不改动测试文件、不能执行破坏性命令。第四个问题有没有必须遵守的项目规则比如必须用中文注释、不能使用any类型。这四个问题的答案就是技能模板正文的骨架。我在写第一个技能的时候跳过了这步直接凭感觉写结果写了满满一页纸的规则真正用起来的时候发现模型不知道该先干什么效果还不如不写。后来每一个技能都先回答这四个问题正文结构就清晰多了。3.2 编写一个真实的项目技能从零开始用一个我实际做过的例子来演示。当时有个团队的项目要求所有代码变更必须符合一套接口规范但OpenCode经常生成不符合规范的结构。我决定做一个“接口变更检查”技能。先按前面说的模板目录结构放在项目级路径.opencode/skills/api-change-check/下面。SKILL.md的frontmatter部分name取api-change-checkdescription我斟酌了很久最终写成--- name: api-change-check description: 当用户修改、创建或讨论项目中API接口定义、接口参数、返回结构、错误码相关代码时使用。重点场景包括修改handler或controller、定义请求响应结构体、增删错误码、涉及接口兼容性的改动。 ---这段描述里其实包含了前面说的三个要素触发动作修改、创建、讨论接口相关代码、具体对象接口定义、参数、返回结构、错误码、触发场景举例handler、请求响应结构体。实测下来模型在遇到相关改动时能正确匹配到技能。正文部分我按照模板的骨架来写但增加了项目特有规则# 接口变更检查 你在团队中负责保证接口变更符合项目规范。收到相关代码后执行 1. 识别本次涉及的API路径、HTTP方法、参数和返回结构。 2. 对照项目接口规范检查参数命名是否使用snake_case、返回结构是否包裹在统一的data字段内、错误码是否在预定义范围内。 3. 检查是否破坏现有兼容性。如果原有字段被改名或删除标记为阻塞问题。 4. 输出检查结果格式为路径 | 问题 | 严重级别 | 修改建议。 ## 项目特有规范 - 所有接口参数必须显式声明类型禁止使用无类型的map传递参数。 - 错误码必须从 constants/errno.go 中引用禁止硬编码数字。 - 分页参数统一为 page 和 page_size禁止使用 offset。写完之后我把项目里一个真实的接口模块调出来试了一次让它检查某次改动。第一次运行时它确实触发了技能但输出格式跟预期有出入。我在正文里补了一句“每一条问题单独一行禁止使用表格以外的复杂格式”第二次输出就规整多了。这个调整过程说明了技能模板不是一锤子买卖需要在实际使用中迭代。3.3 多文件技能与辅助资源引用SKILL.md写到最后一定会遇到一个问题技能正文太长或者需要引用项目里大量的规范文件。如果全塞进SKILL.md文件会变得臃肿模型的注意力也会被稀释。这时候就要用多文件结构。OpenCode的技能目录里除了SKILL.md还可以放辅助文件。比如你可以在技能目录下建一个references/子目录放详细的规范文档、代码示例、检查清单。SKILL.md里只写核心流程提到“详细规范见references/api-conventions.md”即可。模型在实际使用场景中会根据引用去读取对应文件。这里有一个需要控制的风险辅助文件不是越多越好。模型在读取文件时是有上下文窗口限制的如果你把一个两万字的规范文档丢进去它会为了塞下这些内容而开始遗忘用户的实际诉求。我个人的建议是辅助文件里的内容尽量做成“检查条目式”的精简格式长篇大论的背景说明就别放进来了。一个技能的总引用量控制在两千字以内是比较舒服的。3.4 在OpenCode里加载和验证技能写完技能怎么知道它到底有没有被正确加载我的做法是分两步。第一步是看目录结构是否正确。在技能目录下运行查看命令确认SKILL.md在正确位置文件名大小写没问题frontmatter的---没有写错。OpenCode对技能扫描一般是按目录递归查找如果目录层级放错或者文件名写错技能就是白写了而且不会有明显报错。第二步是实际对话测试。我会直接给出一个明确触发场景的指令比如“帮我对src/api/user.go做一次接口变更检查”然后观察它是否进入了技能设定好的角色。一个有效的判断方法是看它的回答风格是否和技能正文吻合。如果它开始按我在技能里定义的格式输出说明加载成功如果回答得天花乱坠、完全没有步骤感就得回头检查技能目录路径和描述是否匹配。4. 安装、配置与编辑器集成4.1 OpenCode安装方式与那个常见报错聊完技能本身再说说环境。很多新手卡在第一步安装上这里展开讲讲。OpenCode官方提供了多种安装方式最主流的是通过npm安装命令是npm install -g opencode-ai。也有脚本安装方式直接执行官方安装脚本即可。安装过程中最经典的问题就是热搜词里那个报错无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错是Windows PowerShell下典型的“命令不存在”提示出现它基本可以断定是两种情况。第一种情况是npm全局安装目录没有加到系统的PATH环境变量里。npm全局包默认会装到一个目录在Windows上通常是%APPDATA%\npm如果这个目录不在PATH里打开新的PowerShell窗口执行opencode时系统就找不到这个命令。解决办法是把该目录手动加入系统环境变量PATH然后重启终端。第二种情况是某些安全软件或者权限配置导致安装脚本没有真正完成。比如系统打开PowerShell脚本执行策略限制npm安装时执行postinstall脚本失败。这种情况可以检查npm的日志或者用管理员权限重新执行安装命令。4.2 配置模型提供方让技能跑起来OpenCode本身不提供模型它需要一个后端模型的API才能工作。这意味着你首先要有一个可用的模型服务。常见的做法有两种一是使用各大模型服务商提供的API配置对应的key二是使用本地模型服务通过兼容的接口地址接入OpenCode。具体配置通常通过登录命令来完成。执行opencode auth login按照交互提示选择对应的模型服务商粘贴API key。如果使用的是本地模型服务或者自定义网关则需要在配置文件中设置基础地址。这里有一个我踩过的坑如果配置了代理或者自定义base URL记得确认终端里的环境变量是否生效否则OpenCode发出的请求会直接打到默认地址导致鉴权失败。配置完成后用一条最简单的指令测试“你好请回复收到”确认模型能正常返回再开始做技能测试。4.3 在VSCode和IDEA里用OpenCodeOpenCode虽然核心是终端工具但它也提供了编辑器插件方便在开发环境里直接调用。VSCode有对应的OpenCode扩展安装后在侧边栏会出现会话面板可以在编辑器里直接选中代码然后发起指令。IDEA也有官方或社区插件。这些插件本质上还是跟终端里的OpenCode交互但好处是你可以直接利用编辑器的文件选择、代码高亮能力不用来回切换窗口。我在实际使用中的工作流是写代码用编辑器跑技能指令用终端查技能触发细节用插件面板。如果你主要依赖IDE做代码审查那直接在插件面板里触发技能会比在终端里更顺。有一点要注意插件的技能加载路径和终端是一致的所以如果你在项目级目录配置了技能插件同样能识别。4.4 常见报错与排查速查表把安装配置阶段的高频问题整理成一个表方便遇到时报错就知道怎么处理。报错或现象可能原因排查方向opencode无法识别为cmdletnpm全局目录不在PATH检查PATH添加npm全局目录安装过程卡住或失败网络问题或脚本执行策略限制检查网络换镜像源用管理员PowerShellauth login后请求仍然401key配置未加载或环境变量冲突检查环境变量重启终端重试登录技能文件存在但不触发目录路径不对或description写得模糊确认技能目录在正确位置优化description插件面板无法连接终端会话插件版本与OpenCode版本不匹配升级插件和OpenCode到最新版输出内容乱码或格式错乱终端编码问题在PowerShell中执行chcp 65001切换UTF-8编码5. 技能模板优化的实战经验5.1 描述写得好的标准能触发、不多触发前面反复强调description重要这里给出一个更具体的标准。一个好的技能描述应该做到两点该触发的时候一定能触发不该触发的时候坚决不触发。我在写api-change-check这个技能时最初的描述没有提到“接口兼容性”结果有一次用户只是讨论技术方案、并没有实际改动接口模型仍然触发了技能并输出了一大段检查报告很干扰。后来我在描述里加了“涉及接口兼容性的改动”和“重点场景包括”把触发边界收紧误触发的情况就明显减少了。写描述时你可以站在模型的角度想用户说什么话、做什么操作时我作为模型觉得这个技能是相关的把这些场景写进去就行。5.2 正文与元数据分离保持模板的可维护性技能维护久了你会发现最难的往往不是写而是改。今天项目规范升级了明天代码风格变了如果所有内容都堆在SKILL.md里每次修改都要小心不要破坏其他部分。我的建议是将正文分成稳定的“方法论部分”和易变的“项目规范部分”。方法论部分放在SKILL.md主体比如审查流程、输出格式项目规范部分单独放到references/project-rules.mdSKILL.md里只保留一行引用。这样规范变更时只需要改辅助文件不需要动技能的整体结构。这个做法同时也是对前面多文件技能的延伸属于模板层面的工程化思路。5.3 技能的粒度宁粗勿细还有一个常见问题是技能的粒度把握。初学者容易把技能写得极其细分比如“检查错误码”一个技能、“检查分页参数”一个技能、“检查命名规范”一个技能。结果就是技能库几十个文件看起来很多实际模型根本不知道该选哪个性能反而下降。经验法则是一个技能至少覆盖一类完整任务而不是一个动作。比如“接口变更检查”就包含错误码、参数、兼容性所有检查点它是一个完整的任务。你可以通过技能内的段落来区分不同检查项而不是拆成多个技能。过细的拆分只会增加匹配难度不会提升输出质量。5.4 迭代技能模板的节奏与方法技能模板写完只是开始我用了一个简单的迭代方法每次技能实际触发后如果发现输出不符合预期我就记录下是哪一条指令没起作用、缺少哪一条规则。积累三次反馈后统一修改一次SKILL.md而不是每次发现小问题就改避免频繁修改导致技能行为不稳定。在这个迭代过程中有个细节值得注意。OpenCode的会话上下文是有限的技能正文写得再长模型真正记住并严格执行的往往是靠前和靠后的部分。所以我会把最重要的规则放在正文开头把“注意事项”放在最后中间的细节尽量精简。这个布局看起来没什么技术含量但对实际执行质量影响很大也是我在多次踩坑之后总结出来的经验。6. 最后再说点实际的东西写到这里OpenCode技能系统的基础技能模板这整条链路已经走得差不多了从理解技能系统的价值到掌握SKILL.md的格式到动手做一个真实技能再到安装配置和问题排查。我个人的体会是技能系统的学习曲线并不陡峭真正的门槛在于转变思路。你不能再把AI助手当成一个每次都要重新调教的工具而是把它当成一个需要建立工作标准的协作者。技能模板就是你和它之间的那份“团队章程”。如果你现在正准备开始用OpenCode我建议第一件事不是急着写技能而是先用默认配置把一个具体任务跑通观察它在哪些环节不听话、在哪些环节需要你反复补充说明。这些痛点就是你第一个技能的需求来源。从你最痛的一个场景入手套用本文的基础模板写一个技能再用上几轮迭代修正。等第一个技能真正好用起来你自然就理解了整个机制后面再扩展技能库就只是重复劳动了。最后再分享一个小技巧技能目录本身就是可以纳入git管理的。把全局技能放在一个独立的dotfiles仓库里项目级技能跟着项目仓库走。这样即使换了电脑或者重装系统一条命令拉下来你所有的技能模板和规范顷刻间就回来了。这个习惯我从一开始就养成了后来重装环境时省了非常多事。