1. opencode Skills 到底是什么从 SKILL.md 到 Agent 的加载链路如果你最近在折腾 opencode大概率会碰到一个词Skills。简单说Skills 就是一套可复用的指令模块用 SKILL.md 文件定义让 Agent 在需要的时候按需加载特定的行为规范和工作流程。它不是插件也不是脚本而是一份写给模型看的“操作手册”——你告诉它遇到什么任务该怎么做它照着执行。适合谁适合那些想让 opencode 按自定义技能稳定执行任务的开发者。比如你希望 Agent 每次生成文档都遵循固定格式、每次处理数据都走同一套校验流程或者你想把团队内部的编码规范固化下来Skills 就是最直接的落点。它的工作链路其实不复杂。Agent 启动后会先扫描当前目录下所有 SKILL.md 的元信息YAML 前言部分把技能列表交给模型。模型根据你的指令判断该用哪个技能然后告诉 Agent。Agent 再去加载对应技能的完整指令层内容交给模型执行。如果技能里还引用了 assets、reference、scripts 这些资源Agent 会在后续需要时再按需加载。这里有个关键点全局 Skills 的内容是一次性全部加载的而项目级和子文件夹级的 Skills 是按需加载。这个区别直接决定了你该把技能放在哪里。全局路径在 Windows 下是C:\Users\你的用户名\.config\opencode\skills.mdmacOS 下是~/.config/opencode/skills.md。项目级放在project/.opencode/skills子文件夹级放在project/.opencode/名称/skills。我试过把通用规范放全局、把项目专属逻辑放项目级效果比较稳。全局的适合放那些“永远生效”的约束比如输出语言、代码风格项目级的适合放跟当前仓库强相关的流程比如构建命令、测试路径。这样模型不会一次性被太多无关指令淹没触发准确率也更高。理解了这个分层逻辑你就能判断自己的技能该放哪一层。接下来我们先把 TaoToken 的接入配好因为 opencode 要调用模型得先有一个稳定的 API 入口。2. TaoToken 前置配置给 opencode 一个稳定的模型入口opencode 本身是个客户端它需要连到模型服务才能跑起来。TaoToken 在这里扮演的角色就是提供统一的 API 入口让你不用在多个模型供应商之间来回切换配置。官网是 https://taotoken.netAPI 地址是 https://taotoken.net/api。配置方式有两种取决于你用的是什么形态的 opencode。如果你用的是 Claude Code 类的接入方式通常需要设置环境变量如果你用的是配置文件驱动的形态那就写 JSON 或 TOML。先说环境变量这种方式。你需要在 shell 的配置文件里加上这几行export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEY你的TaoToken密钥如果你用的是 Anthropic 兼容模式变量名会不一样export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的TaoToken密钥密钥在控制台的 API Keys 页面生成地址是 https://taotoken.net/console/api-keys。生成后复制出来粘贴到上面的配置里就行。再说配置文件这种方式。opencode 支持用opencode.json或config.toml来声明模型。以 JSON 为例你可以在项目根目录或者全局配置目录下建一个opencode.json{ provider: { taotoken: { baseURL: https://taotoken.net/api, apiKey: 你的TaoToken密钥, model: claude-sonnet-4-20250514 } } }如果你更习惯 TOML等价写法是这样[provider.taotoken] baseURL https://taotoken.net/api apiKey 你的TaoToken密钥 model claude-sonnet-4-20250514这里有个细节要注意Base URL、Key、Model ID 这三件套必须同时存在缺一个都会导致请求失败。很多人只配了 Base URL 和 Key忘了指定 Model ID结果模型不知道该调哪个就会报错。配好之后你可以先用一个最简单的请求验证连通性curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的TaoToken密钥 \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }如果返回里有choices字段说明链路通了。如果返回 401那就是 Key 不对如果返回local proxy failed那通常是 Base URL 写错了或者网络层有问题。TaoToken 的接入文档在 https://taotoken.net/doc里面有更细的参数说明。配好这一步opencode 才有模型可用接下来才能谈 Skills 的加载和触发。3. 可复制配置SKILL.md 模板与 YAML 声明实战现在进入正题。Skills 的核心就是 SKILL.md 文件它由两部分组成YAML 前言元信息和 Markdown 正文指令层。YAML 前言必须放在文件最开头用---包裹。先看一个最小可用的模板--- name: docx-generator description: 当用户需要生成 Word 文档时使用此技能支持标题、段落、表格和列表的规范化输出。 --- # DOCX 生成规范 ## 输出结构 1. 文档必须包含标题、正文、结尾三部分。 2. 标题使用一级标题正文使用段落列表使用无序列表。 3. 表格必须包含表头且表头加粗。 ## 格式要求 - 段落之间空一行。 - 代码块必须标注语言。 - 禁止使用 emoji。 ## 示例 输入生成一份项目周报 输出按上述结构生成 Markdown再转换为 DOCX。这里name字段有严格约束1 到 64 个字符只能包含小写字母、数字和连字符不能以连字符开头或结尾不能有连续连字符而且必须与父目录名称匹配。也就是说如果你的技能目录叫docx-generator那name也必须是docx-generator。description字段是 1 到 1024 个字符要描述清楚技能的作用和何时使用。这里的关键是“包含具体关键词”因为模型就是靠这段描述来判断该不该加载这个技能的。你写得越具体触发越准。再看一个更贴近实际项目的例子这次是代码审查技能--- name: code-review description: 当用户提交代码审查请求时使用检查命名规范、错误处理、边界条件和测试覆盖。 --- # 代码审查流程 ## 检查项 1. 变量命名是否使用驼峰或下划线且语义清晰。 2. 是否有未处理的异常分支。 3. 边界条件是否覆盖空值、零值、最大值、最小值。 4. 是否有对应的单元测试。 ## 输出格式 - 按文件分组列出问题。 - 每个问题标注严重级别高、中、低。 - 给出修改建议不直接改代码。写完之后把文件放到对应目录。项目级技能放在project/.opencode/skills/code-review/SKILL.md注意目录名要和name一致。子文件夹级放在project/.opencode/模块名/skills/code-review/SKILL.md。如果你想让技能引用额外的资源可以在技能目录下建assets、reference、scripts三个子目录。assets放图片音频reference放更细的 Markdown 文档scripts放可执行脚本。Agent 会在需要时按需加载这些内容不会一次性全读进来。配置完成后你可以用 opencode 的模型对话功能先验证技能是否被识别。打开 https://taotoken.net/chat在对话里输入“列出当前可用技能”看返回里有没有你刚写的code-review。如果有说明元信息已经被扫描到了。4. 验证请求从加载到触发的完整链路演示配置写好了怎么确认技能真的生效这里给你一套可复现的验证动作。第一步确认文件结构。假设你的项目根目录是/home/user/myproject那技能文件应该在/home/user/myproject/.opencode/skills/code-review/SKILL.md你可以用ls -R .opencode检查一下确保路径和文件名都对。注意SKILL.md是大写有些系统对大小写敏感。第二步启动 opencode 并进入项目目录。Agent 启动时会扫描.opencode/skills下的所有SKILL.md读取 YAML 前言。你可以在启动日志里看到类似loaded skill: code-review的输出。如果没有先检查文件是不是放在了正确的位置。第三步触发技能。在对话里输入一个明确的请求比如“帮我审查一下 src/utils.js 这个文件”。模型会先看到技能列表判断code-review的 description 匹配当前任务然后告诉 Agent 加载这个技能的完整内容。Agent 加载后把指令层交给模型模型再按指令执行审查。第四步观察输出。如果技能生效输出应该遵循你在 SKILL.md 里定义的格式按文件分组、标注严重级别、给出修改建议。如果输出是随意的、没有结构的那说明技能没被加载。这里有个排查技巧你可以在 SKILL.md 的指令层里加一句“在输出开头打印 [code-review loaded]”这样一眼就能看出技能有没有被触发。验证通过后再把这句删掉。第五步验证按需加载。如果你在技能里引用了reference/detail.md可以在对话里问一个需要细节的问题看 Agent 会不会去读那个文件。如果读了说明按需加载链路是通的。整个链路走下来你应该能清楚看到元信息被扫描 → 模型选择技能 → Agent 加载指令层 → 模型执行 → 按需加载资源。任何一环断了技能都不会生效。如果你在验证过程中想换个模型试试效果可以直接在模型对话页面切换地址是 https://taotoken.net/chat。不同模型对指令的遵循程度不一样有的更严格有的更灵活多试几个能找到最适合你技能的那个。5. 常见报错排查401、local proxy failed、reading choices 怎么解配 Skills 的过程中报错基本集中在几个地方。我按真实遇到的顺序列一下。401 Unauthorized。这个最直接就是 Key 不对。检查三件事Key 有没有复制完整、有没有多余空格、是不是用在了正确的环境变量里。如果你用的是OPENAI_API_KEY但实际走的是 Anthropic 兼容模式那也会 401。解决办法是确认你用的变量名和 API 模式匹配。local proxy failed。这个通常出现在 Base URL 配置错误的时候。比如你写成了https://taotoken.net/api/多了个斜杠或者写成了https://taotoken.net少了/api。正确的写法是https://taotoken.net/api不带尾部斜杠。另外如果你本地有网络层工具在跑也可能干扰请求先关掉再试。reading choices 报错。这个一般是因为返回体里没有choices字段说明请求虽然发出去了但模型没正常返回。常见原因是 Model ID 写错了。比如你写了个不存在的模型名服务端不知道调哪个就会返回空结构。解决办法是确认 Model ID 拼写正确并且你的账号有权限调用那个模型。OAuth 相关报错。如果你用的是 Claude Code 类的接入方式可能会碰到 OAuth 流程的问题。这时候要检查~/.claude/settings.json或对应的配置文件里Base URL 和 Key 是不是都指向了 TaoToken。如果之前配过别的服务残留的配置会冲突。建议先清空再重新写。技能不触发。这个不是报错但比报错更让人头疼。排查顺序是先确认SKILL.md的 YAML 前言格式对不对---必须独占一行再确认name和目录名一致然后确认description里有没有具体关键词。如果 description 写得太泛比如“处理各种任务”模型根本判断不出什么时候该用。技能触发了但输出不对。这通常是指令层写得不够明确。模型对模糊指令的解读差异很大。解决办法是把步骤拆细每一步都给出明确的输入输出示例。比如不要写“格式化输出”而要写“输出必须包含三列文件名、问题类型、建议”。还有一个容易忽略的点全局 Skills 是一次性全部加载的。如果你在全局放了太多技能模型的选择空间会变大触发准确率反而下降。建议全局只放通用规范项目专属的放项目级。如果你在排查过程中需要看更细的 API 返回可以在请求里加上stream: false这样能拿到完整的 JSON 响应方便定位问题。接入文档在 https://taotoken.net/doc里面有各字段的说明。6. 长期编码与 Agent 场景把 Skills 用成稳定生产力Skills 真正发挥价值的地方是长期编码和 Agent 场景。单次对话里触发一个技能不难难的是让 Agent 在连续任务里稳定地按你的规范执行。这里的关键是分层。全局 Skills 放那些“永远不该变”的约束比如输出语言、代码风格、禁止事项。项目级 Skills 放跟仓库强相关的流程比如构建命令、测试路径、部署步骤。子文件夹级 Skills 放模块专属的逻辑比如某个服务的接口规范。这样分层之后Agent 在不同目录下工作时加载的技能集是不一样的。它不会在写前端代码时被后端的规范干扰也不会在处理数据脚本时被 UI 规范带偏。另一个技巧是把技能和 Coding Plan 结合起来用。Coding Plan 适合长期编码任务地址是 https://taotoken.net/coding-plan。你可以在 Plan 里预设好技能加载策略让 Agent 在每次任务开始时自动扫描技能列表按需加载。这样你就不用每次手动提醒它“记得用 code-review 技能”。对于 Agent 场景建议把技能的指令层写得像一份 SOP。每一步都有明确的输入、动作、输出。模型在执行时会按这个 SOP 走减少自由发挥的空间。你可以在指令层里加一句“如果遇到未定义的情况先询问用户不要自行决定”这样能避免 Agent 在边界情况下乱来。还有一点技能的description要定期维护。随着项目演进有些技能可能不再适用有些新场景需要新技能。建议每个月过一遍技能列表把过时的删掉把新的补上。技能列表越干净模型的选择越准。最后如果你想让技能在团队里共享可以把项目级 Skills 提交到仓库里。这样每个成员拉下代码后Agent 自动就能用上同一套规范。全局 Skills 则适合放个人偏好不强制同步。整套流程走下来你会发现 Skills 不是一次性配置而是需要持续迭代的。从 SKILL.md 的编写到 YAML 声明的约束再到 Agent 的加载链路每一环都影响最终的执行效果。把这几步做扎实opencode 才能真正按你的意图稳定干活。