王释易1. 先搞明白OpenCode技能系统到底解决什么问题
1.1 从“靠提示词碰运气”到“给模型发工具手册”
刚开始接触OpenCode的时候，我的用法很简单：在会话里把需求描述得特别详细，让模型一步步执行。遇到能干的模型，效果还不错；遇到状态一多、任务一长的场景，模型就开始“自由发挥”——明明上一步刚说过要用某个脚本，下一步却自己另起炉灶；明明要求输出JSON，结果夹带一堆解释文本。问题不在于模型笨，而在于我把“怎么做”的说明全塞在临时对话里，模型只能靠上下文猜我的意图，猜得准全靠运气。
OpenCode的技能系统就是为这个问题设计的。它的核心思路是：把一套固定流程、固定脚本、固定输出格式提前封装成一个“技能模板”，模型在会话里根据任务描述自动扫描技能清单，发现合适的就加载使用。换句话说，我不需要每次都把步骤讲一遍，只需要让模型知道“有这么一个技能，它的工作流程是什么，遇到什么情况该调用它”。
这个设计尤其适合三类场景：一类是重复性极高的固定操作，比如批量重命名文件、格式化代码、扫描日志中的异常；一类是需要保证输出格式稳定的任务，比如生成指定结构的报表、提取特定字段；还有一类是需要多个步骤串联的流程，比如拉取数据、清洗、分析、输出结果。
1.2 技能模板的运行链路：模型扫描、匹配、加载、执行
技能系统的工作方式可以理解为一个“自动派单”的过程。OpenCode在启动会话时，会从配置的技能目录里读取所有技能模板，每个模板的核心是一份SKILL.md文件，文件里用结构化格式写清楚技能的用途和操作步骤。当你在对话中提出一个需求，模型会先检索有哪些技能与当前需求相关，然后读取匹配技能的全文，按其中的指令执行。
这个机制和普通的“提示词模板”有本质区别。提示词模板只是把一段文字插入对话，模型看到什么就临时理解什么；技能模板则多了一个“注册—扫描—匹配—加载”的链路，模型不是被动接收文字，而是主动查找技能库。就好比一个是临时抓个人来干活，一个是去工具库里拿对应的专用工具。
所以，基础技能模板的真正价值，在于“结构化的可复用性”。你写一次，以后所有会话都能自动命中这个技能，不需要重复维护一大段提示词。这个前提是：模板本身的字段要写得足够规范，目录位置要放对，脚本要能被正确调用。接下来我按自己的实操过程把这些细节逐一拆开讲。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. OpenCode基础技能模板的结构拆解：SKILL.md、scripts与assets
2.1 技能目录的三种组织方式
OpenCode的技能存放没有强制规定唯一路径，但社区和官方文档里最常用的是三种组织方式，我逐一试过，分别说一下适用场景。
第一种，全局技能目录。放在用户主目录下的.config/opencode/skills/或者OpenCode指定的全局配置目录里，适合那种“不管在哪个项目里都需要用”的技能，比如日志分析、代码格式化、通用工具函数。
第二种，项目级技能目录。放在当前项目的.opencode/skills/下，适合和业务强绑定的技能，比如这个项目的专属构建脚本、数据库迁移脚本、接口联调工具。项目级技能的好处是跟着Git仓库走，团队成员clone下来就能用，不需要每个人都手动配置。
第三种，自定义路径。在OpenCode的配置文件（比如opencode.json）里通过skills字段指定多个目录路径，路径之间用数组组织。这个方式灵活性最高，可以把不同来源的技能分门别类，比如第三方下载的技能包放一个目录，自己写的放另一个目录，互不干扰。
我自己项目的习惯是：全局技能目录放通用型技能，项目级目录放业务型技能，自定义路径基本不常用，除非需要挂载一个外部技能包。你如果刚开始接触，先建全局技能目录就够了，后面有需要再加项目级。
2.2 SKILL.md里的frontmatter和正文到底怎么写
技能的核心文件是SKILL.md，它的格式分为两部分：YAML格式的frontmatter字段区和markdown正文区。这个结构类似很多静态站点生成器里文章头部信息的写法，OpenCode会先解析frontmatter来获取技能的元信息，再把正文当作模型操作的说明书。
frontmatter里最关键的字段是name和description，这两个直接决定了技能能否被正确匹配。name是技能的唯一标识，要求简短且能代表功能，比如log-scanner或者code-formatter。description是给模型看的“检索索引”，必须写清楚这个技能处理什么任务、在什么场景下用、大概怎么做、输出什么格式。注意，description不是给人看的，你的措辞要尽量贴近模型理解任务的方式，写得太抽象会导致模型扫不到这个技能。
举个例子，我写过的一个日志扫描技能，description最初写的是“扫描日志文件中的异常信息”，测试时发现模型经常不匹配这个技能，改成“当用户需要分析日志文件、查找报错信息、统计错误码频次时使用此技能，输入为日志文件路径和过滤关键词，输出为结构化错误报告”之后，命中率立刻提高。原因是后者包含了触发条件、输入形式、输出形式三个维度，模型扫描时更容易判断“当前对话和这个技能匹配”。
正文部分就是给模型看的操作手册，用自然语言描述执行步骤，格式可以灵活，但我建议固定用“目标、输入、步骤、输出、注意事项”五段式结构。这样做的好处是：模型读取时路径非常清晰，不容易漏掉关键步骤；你自己维护时也方便增删内容，不会越改越乱。
2.3 scripts目录与执行权限：模型“动手”的入口
SKILL.md描述的是“怎么做”，真正动手干活的是脚本文件。OpenCode支持在技能目录下建一个scripts目录，把各种可执行脚本放进去，模型在读取SKILL.md后如果需要执行命令，就会去这个目录里找对应的脚本。
脚本类型没有限制，Python、Shell、Node.js都行，但有几个细节需要特别注意。第一，脚本要加上可执行权限，Linux和macOS下用`chmod