我大概是那种懒到极致反而逼出效率的人。前一阵子接手了好几个历史遗留仓库的维护任务每次都要跟AI助手从头解释一遍先看目录结构、再查依赖、然后排查明显问题——解释到第三遍的时候实在受不了了。后来我把这套流程在Opencode里固化成了一个技能之后每次只需要一句话它就会按照我沉淀的标准作业流程把活干完。这篇分享就围绕一件事如何使用Opencode高效创建属于自己的技能。先说明一下背景。Opencode是一个跑在终端里的AI编程代理工具它不像普通聊天界面那样只能一问一答而是可以真正参与项目的分析、修改和执行。很多人在用它的时候停留在当作加强版聊天框的阶段每次干活都要重新写一大段提示词换个场景又得重写一遍。技能Skill就是用来终结这种重复劳动的把一段经过验证的、结构化的指令封装起来让AI在特定场景下自动按照你的标准执行。这篇文章适合所有刚接触Opencode、以及已经用了一段时间但总觉得差点意思的人我会从概念讲到落地再讲到我踩过的坑保证你能直接照着抄。1. 先搞清楚Opencode的技能到底是什么东西1.1 技能不是插件也不是命令别名很多人第一次听说技能这个概念时会下意识拿它跟插件、扩展程序做类比其实这是两种完全不同的东西。插件是往工具里加功能而技能是给工具一份干活的说明书。打个比方插件相当于给你买了一台新的厨房电器技能则是教你怎么把一道菜做到店里的标准——不涉及新增设备只涉及做事的方式。在Opencode里一个技能本质上是一个包含结构化指令的文件集合。它告诉AI模型你接下来要面对什么类型的任务、应该按什么顺序思考、使用哪些工具、最终以什么格式输出。AI本身的能力来自模型技能不赋予它新能力而是约束它把已有能力用在对的方向上。这一点非常关键。模型的能力是通用的但你做事的标准是私有的。两个不同性格的AI加上同一套模型给它们同一个任务产出的质量可能天差地别。差别就来自于你喂给它的上下文和约束。技能的价值恰恰在于把那些你通过反复调教才得到的有效指令固定下来下次不用重新摸索。1.2 为什么我们需要把做事方式封装起来我见过不少同事用AI助手干活的方式是这样的今天想让它检查代码于是写一段详细的提示词运气不错结果还行明天又遇到类似任务重新写一遍但昨晚忘了关键约束结果产出质量明显下滑。这种用法的问题在于经验没有被积累每次都在用全新的对话去挑战同一个不确定性。技能解决的就是这个问题。当你把一套流程封装成技能之后会获得几个实实在在的好处一致性团队里不同人触发同一个技能得到的是同一套流程约束下的结果而不是十个人写出十种风格的提示词然后得到十种质量参差不齐的输出。可复用一次性投入的编写时间换来回无数次稳定的执行。对于我这种经常处理同类型任务的人来说投资回报率高得惊人。可演进技能是文件可以被版本管理。今天发现流程里缺了一步改一下文件就完成了对所有后续执行的升级不用通知任何人。可分享把一个调试好的技能文件发给同事对方放到自己的配置目录里就能用。这比口头传授经验可靠得多。说白了技能就是把你脑子里的标准作业程序从隐性知识变成显性文件。项目里新人上手最快的路径往往不是看文档而是直接用你封装好的技能跑几遍真实任务。2. 环境准备把Opencode装好并弄懂它的配置目录2.1 安装与首次运行Opencode的安装并不复杂它通常以命令行工具的形式分发。我当时的做法是直接用系统的包管理器全局安装一个命令搞定这里就不写具体命令了因为不同操作系统的安装方式略有差异。装完之后在终端里输入工具名看到它进入交互式的命令行界面就说明安装成功。首次运行时程序会引导你完成基础配置核心是两件事选择模型服务商和填入密钥。Opencode本身不内置模型它只是一个接入了各家大模型服务商的代理层所以你需要有自己的模型接口密钥。现在主流的大模型服务商基本都提供兼容接口你把对应的密钥配置进去即可。这里有一个新手非常容易忽略的点不要以为装完就直接能用。命令行工具通常不会给你一个漂亮的图形化引导窗口初始化结束后你大概率会面临一个看起来有点简陋的提示符。别慌先在任意一个项目目录里让它跑一个最简单的任务比如列一下当前目录的结构确认基本链路通了再继续做技能相关的配置。2.2 配置目录与技能存放位置Opencode的配置遵循命令行工具的主流惯例全局配置放在用户主目录下的隐藏配置目录里。以我常用的系统为例就是类似~/.config/opencode/这样的路径。这个目录里通常有一个主配置文件记录你选了哪个模型服务商、密钥怎么读、默认参数是什么。具体文件名和格式可能因为版本迭代有出入运行工具内置的帮助命令就能查到。技能目录则有两种常见的存放位置全局技能目录放在上述配置目录下的skills/子目录里所有项目都能用。项目级技能目录放在某个项目根目录下的隐藏目录里只有在该项目下运行Opencode时才生效。两种方式各有用途。全局技能放那些与项目无关的通用流程比如代码评审提交信息规范化项目级技能放跟当前项目技术栈强绑定的流程比如为本项目的微服务模块生成新接口模板。我第一次配技能目录时就吃了不认真看文档的亏把技能放错了地方结果在另一个项目里怎么触发都没反应。后来学乖了任何时候怀疑技能没生效第一件事就是确认它到底被放在了全局还是项目级目录。2.3 模型选择对技能效果的影响很多人忽略了一个事实技能是写给模型看的剧本但不同的模型对剧本的理解能力是不一样的。同样的技能文件在指令遵循能力强的模型手里可能执行得分毫不差换一个模型可能就丢三落四。这不代表你要为了技能去盲目追求某一个特定模型。我的经验是在编写技能时默认假设模型是个听话但有点笨的新人。指令要拆得足够细步骤不要过度依赖模型的推理能力去脑补中间环节关键节点最好明确写出如果遇到什么情况就做什么动作。这样即使换了模型技能依然大概率能跑出可接受的结果。另外多提一句API的稳定性问题。如果你像我一样经常连续跑多个任务建议在配置里把超时和重试参数调一下避免偶然的网络波动让一个本来很稳的技能突然失败然后你花半小时排查最后发现只是请求超时。3. 创建第一个技能把仓库体检做成标准流程3.1 技能文件的基本结构理论讲了半天该动手了。Opencode里一个技能通常就是一个文件夹文件夹里至少包含一个核心的说明文件我习惯叫它SKILL.md因为Markdown格式既适合人读也适合模型读。一个标准的技能文件夹长这样~/.config/opencode/skills/ └── repo-inspect/ ├── SKILL.md └── checklist.mdSKILL.md是技能的主文件包含两部分内容开头是一段元信息用键值对的形式描述技能的姓名、作用、版本和触发条件正文则是给模型看的实际操作指令。如果技能特别复杂你还可以在同一个文件夹里放辅助文件比如上面例子里的checklist.md用来存放一份详细的检查清单主文件里通过指令让模型去读取它。为什么要把辅助内容拆成独立文件因为模型对上下文的注意力是有限的。如果你把一份五千字的检查清单全部塞进技能主文件里执行到后面模型很容易忘记前面的细节。拆成独立文件之后主文件只负责引导流程详细清单按需读取效果会好很多。3.2 一个可以直接抄的示例下面这个示例是我实际在用的一套仓库体检技能用来快速了解一个新接手仓库的整体状况。你可以直接复制把细节改成自己需要的。--- name: repo-inspect description: 对代码仓库进行结构体检输出结构化报告 version: 1.0.0 trigger: 仓库体检 --- # 仓库体检 ## 目标 在尽量短的时间内了解一个仓库的整体状态发现明显问题并输出一份结构清晰的体检报告。 ## 执行步骤 第一步了解仓库基本盘 1. 读取仓库根目录下的项目描述文件确认项目名称和用途。 2. 遍历根目录识别主要子目录的职责。 3. 识别当前使用的技术栈和语言。 第二步检查依赖状态 1. 找到依赖清单文件。 2. 统计依赖总数标记其中明显过期或存在已知安全隐患的依赖。 3. 检查是否有重复或冗余的依赖声明。 第三步检查代码健康度 1. 查看最近的提交记录了解近期活跃度和改动规模。 2. 识别明显的调试残留例如写死在代码里或日志输出里的调试信息。 3. 找出体积异常庞大的文件重点关注这些文件是否存在拆分必要。 第四步输出报告 严格按照以下格式输出 - 仓库概览名称、用途、技术栈 - 依赖健康度总数、问题数、风险依赖清单 - 代码健康度活跃度、调试残留、超大文件清单 - 改进建议按优先级从高到低排列每条建议不超过两句话你可以看到这个技能文件的核心逻辑特别朴素给目标、给步骤、给输出格式。没有华丽的辞藻全是干巴巴的指令。之所以这样写是因为模型在处理长指令时对明确动词明确对象的遵循程度远高于建议你考虑看看这种模糊表达。3.3 运行与验证技能文件保存好之后怎么确认它真的生效在项目目录下启动Opencode然后用自然语言触发它。比如我会直接输入一句对当前仓库做一次仓库体检。这里要注意触发方式。有些版本支持通过配置里的trigger字段做精确匹配有些版本则更依赖模型根据description自动判断何时该调用技能。我的建议是不要把触发条件写得过于苛刻比如要求用户必须输入某个特定短语才触发否则日常使用中你很快会因为忘了确切短语而放弃使用技能。更稳妥的做法是把描述写清楚让模型在用户意图匹配时自动使用这个技能。第一次执行的时候我强烈建议你全程盯着它的输出观察每个步骤是否符合预期。通常第一版技能跑出来会有一两个地方不对这很正常。我的经验是不要急着改技能文件先把这次执行暴露出的问题记下来等完整跑完一遍再根据问题统一修改。这样能避免你陷入改一下、跑一次、再改一下的无限循环。4. 让技能真正聪明起来变量、工具与流程编排4.1 用变量让技能适配不同场景你很快会发现有些技能的内容是高度相似的只是每次针对的具体对象不同。比如检查某个目录下的代码规范性和检查另一个目录下的代码规范性——两者的流程几乎一样唯一区别是目标路径。如果你为每个目录写一个技能那是蠢办法。聪明的做法是用变量。Opencode的技能文件通常支持在指令中引用调用时传入的参数比如用类似{{target_dir}}这样的占位符来代表用户指定的路径。在技能文件里写上第一步先进入 {{target_dir}} 目录读取该目录的结构然后在调用时告诉它检查 src/modules 目录的规范性模型就会自动把占位符替换成你传入的路径。这看起来只是一个小改进但实际体验差别巨大。没有变量的时候一个技能只能解决一个固定场景你得为 检查模块A检查模块B 各准备一套技能有了变量之后一个技能覆盖所有同类场景这才是一次封装到处复用的真正含义。4.2 在技能里约定工具的使用Opencode区别于普通聊天界面的重要一点就是它能调用真实的工具读写文件、执行终端命令、搜索项目内容等。技能文件里应该明确约定每个步骤使用哪个工具、允许做哪些操作、禁止做哪些操作。比如在上面的仓库体检技能里我会在说明文件中补充一句所有检查操作只读不得修改任何文件执行命令时优先使用只读命令如列出目录、显示文件内容等避免无意中触发构建或修改操作。这个约束极其重要。模型没有你那么强的分寸感你让它检查依赖它可能顺手就给你执行了依赖更新命令然后留下一堆你并不想要的变更。在技能里用白名单和黑名单来约束工具行为相当于给AI上了一道保险。还有一个细节工具调用失败时怎么处理。我在技能里通常会让模型先重试一次如果仍然失败就停止并报告而不是自行发挥找替代方案。因为很多时候自行发挥就是灾难的开始。4.3 多步骤编排与技能联动单个技能处理单次任务这是最基础的使用方式。更进一步的做法是把技能做成流水线一个技能的输出成为下一个技能的输入。举个例子。我有一套新功能开发的流水线第一步用一个技能分析需求并拆解任务清单第二步用一个技能生成代码框架第三步用一个技能生成配套测试。这三个技能相互独立但通过执行顺序形成了编排。你只需要在第一个技能的最后一步写上将生成的任务清单作为后续功能的输入整个流水线就能顺畅跑下来。这种编排方式比把三个技能合并成一个巨型技能要可靠得多。原因在于每个技能保持单一职责指令简洁模型执行时不容易混乱同时你可以在任意环节插入一个中间步骤灵活度大大提高。但我要提醒一句不要过度设计。流水线虽然听起来高级但每个环节都有失败的可能环节越多整体稳定性越差。我的经验是先让单个技能稳定运行一段时间确认它真的靠谱之后再去考虑串联。宁可要一个能跑通的简单流程也不要一个大概率断裂的复杂编排。5. 实战沉淀我日常开发中最常用的一批技能5.1 技能清单与效果对比用得多了之后我沉淀了一批频率极高、收益明显的技能。下表是我的常用清单列出来给大家做个参考技能名称核心用途触发场景收益点repo-inspect仓库结构体检新接手仓库、定期巡检十几分钟摸清仓库全貌commit-msg规范化生成提交信息每次提交代码前提交历史整齐可读code-review代码评审合入主干前提前拦截明显问题test-gen为模块生成测试用例新功能完成时补齐测试覆盖dep-audit依赖安全检查每月例行发现过时和高危依赖refactor-plan重构方案设计遇到代码坏味道时输出可执行的重构步骤这里我想特别强调一下收益点这一列。很多人写技能时只盯着能自动化什么却忽略了省下的时间是否值得。我的判断标准很简单如果一个任务你手工做需要十分钟以上、并且未来还会重复遇到就值得为它写技能。像仓库体检这种每接手一个新项目都要做的事投入半小时写技能长期来看稳赚不赔。5.2 两个典型技能的完整内容参考除了上面展示的仓库体检技能我再拿commit-msg这个技能说说因为它特别能体现技能如何约束输出质量。写提交信息的痛点在于模型很容易生成那种修复了一些bug更新了代码的废话提交信息。我调教了很多次之后发现关键在于给足结构约束和反例。技能文件里我明确列出了提交信息的格式模板、允许使用的动词列表还专门写了一个反面示例段落把那些看起来没毛病但实际上没有任何信息量的写法列出来让模型知道哪些是不允许的。这里有个特别有用的技巧在技能里写反例比只写正例有效得多。模型对不该做什么的指令遵循度往往高于该做什么的模糊要求。把常见的烂输出直接示众它就知道你要的质量底限在哪里了。另一个值得参考的是code-review技能。我在这份技能里除了常规的检查步骤还专门规定了报告的呈现方式必须按严重程度给问题分级每一个问题都要带具体的文件路径和行号并且给出至少一条修复建议。理由是评审意见如果只停留在这里写得不好这种层面基本等于没说把问题定位精确到行、把建议给到可执行才是真正有价值的评审。6. 技能维护与避坑别让技能变成第二套烂代码6.1 技能失效的常见原因技能写出来不是一劳永逸的。我踩过的坑不少总结一下最常见的失效原因你遇到类似情况可以直接对照排查指令过于抽象。技能文件里全是优化代码质量提高可维护性这类形容词模型根本不知道该执行什么。解决方案是把动作动词化提取重复代码到公共函数将超过两百行的函数拆分。上下文过载。一份技能文件塞了几千字模型执行到中后段已经把前面的关键约束忘了。解决方案是拆分文件把详细清单放到辅助文件里按需读取。步骤顺序不合理。技能要求模型先评估影响范围再动手修改但模型在实际执行中经常跳步。解决方案是在关键节点明确加上没有完成第X步之前禁止进入下一步骤。未定义边界条件。什么情况下应该停止、什么情况下应该向用户确认、什么情况下允许自己决定这些如果不写清楚模型就会替你做了让事后头疼的选择。模型本身的差异。之前也提过不同模型对指令的理解和遵循能力不同。某厂商的模型跑得好好的技能换个厂商的模型可能输出质量断崖式下跌。如果你经常切换模型技能文件里要尽量避免依赖单一模型特有的能力。6.2 排查思路当某个技能突然不好使了我的排查链路是固定的分享给你参考第一先确认是技能问题还是环境问题。重新跑一次最简单的基础任务如果基础任务正常说明Opencode本体和模型链路没问题问题出在技能上。第二把技能内容简化到极致。注释掉大部分指令只保留核心步骤看能不能跑通。如果能跑通说明问题出在被注释掉的某段指令里逐步恢复即可定位。这跟写代码时二分排查问题的思路完全一致。第三检查模型的完整输出过程而不只是看最终结果。很多时候技能看起来没生效其实是模型在某一步误解了指令然后沿着错误方向执行了很久。你需要在输出过程中捕捉到那个最初的偏差点才能精准修复技能文案。6.3 技能版本管理与演进最后说一个很多人都会忽略的点技能文件也是代码也要版本管理。我会把你的整个技能目录放进一个独立的代码仓库里每次修改技能都走提交记录。这样做的好处是一旦新改的技能表现不佳你可以快速回退到上一个可用版本。我还习惯给每个技能文件加上版本号放在开头的元信息里。版本号不光是给自己看的也是给模型看的当它在执行中发现技能文件描述的流程与代码库实际情况不符时版本号能够帮助它判断是不是该提醒用户更新技能。技能本身也需要定期再训练。我会在每个月例行检查时专门花一点时间看看哪些技能已经很久没被触发了。长期不用的技能要么是场景已经不存在了要么是使用门槛太高导致大家不愿意用。如果是后者我会想办法降低调用成本比如优化触发方式、简化不必要的步骤。如果技能已经不适应现状了该删就删不要让它躺在目录里给你造成假的资产感。最后分享一个小技巧。我后来发现在技能文件末尾放一段自查清单比在前面写更多详细步骤更管用。所谓自查清单就是在流程最后让模型逐项检查自己有没有完成关键约束。比如在仓库体检技能的最后加一句输出报告前逐项检查是否覆盖了依赖检查是否指出了具体文件路径建议是否按优先级排序模型在执行完任务后对着清单过一遍很多低级遗漏就会被拦下来。这个技巧几乎可以套用到任何技能上谁用谁知道。
