1. 为什么我要把 Opencode 技能当代码来管Opencode 的 skill-creator 能把一次会话里的操作过程固化成可复用的技能文件这件事本身不新鲜。真正让我踩坑的是技能文件写出来之后放在本地改了几版自己都记不清哪版能用换台机器就找不到了。技能创建、版本管理、配置接入这三件事如果不串起来skill-creator 产出的东西就是一次性的。这篇要解决的就是这条链路用 Opencode 配合 skill-creator 把重复劳动沉淀成技能用 Git 给技能做版本追踪再通过 TaoToken 统一 Key 和 API 通道让 Opencode 以及其它 AI 工具走同一个入口。适合已经在用 Opencode、想把自己的操作经验变成可复用资产的人也适合刚接触 skill-creator、不清楚技能目录和配置文件怎么摆的新手。我会按可跟做的顺序写先讲技能目录怎么初始化再给 settings.json 和 config.toml 的骨架然后演示 skill-creator 的完整迭代流程最后把技能提交进 Git并用 TaoToken 的 API 通道验证请求能跑通。每一步都有可复制的片段和验证动作你照着敲就能得到自己的第一个受版本管理的技能。2. TaoToken 前置统一 Key 与 API 通道在动手写技能之前先把模型通道准备好。Opencode 这类工具本身不绑定某一家模型服务它需要一个兼容的 API 入口。TaoToken 在这里的角色是统一入口你申请一个 Key拿到一个 API 地址之后 Opencode、脚本、其它 AI 工具都指向它不用每个工具单独配一套凭证。官网入口在这里注册和查看文档都从这进https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址单独记一下配置里要填的就是它注意这个地址不带跟踪参数https://taotoken.net/api拿到 Key 的路径是控制台里的 API Keys 页面创建后复制那串以 sk- 开头的字符串只显示一次先存到密码管理器里。后面 settings.json 和 config.toml 都会用到它。注意Key 不要直接写进会提交到 Git 的配置文件。技能仓库是公开或团队共享的凭证一旦进版本历史就很难彻底清除。用环境变量引用配置文件里只留变量名。如果你后面要长期跑编码类任务或者 Agent 流程可以顺带看一下 Coding Plan 的说明它和按量调用是两种计费思路选哪个取决于你的使用频率。模型对话入口可以用来快速验证 Key 是否有效不用写代码就能发一条测试请求。3. 可复制配置技能目录、settings.json 与 config.toml3.1 初始化技能目录先确定技能根目录。Opencode 默认会从用户配置目录读取技能我习惯在项目里也放一份方便跟项目一起做版本管理。目录结构建议这样opencode-skills/ ├── skills/ │ └── git-merge-repos/ │ ├── SKILL.md │ └── examples/ ├── settings.json ├── config.toml └── .gitignore建目录的命令mkdir -p opencode-skills/skills/git-merge-repos/examples cd opencode-skills git init每个技能一个子目录目录名就是技能名用短横线连接的小写英文。SKILL.md 是技能主体examples 放测试用例和边界场景方便后面迭代时对照。3.2 settings.json 骨架settings.json 管的是 Opencode 运行时的行为比如默认模型、技能加载路径、超时。下面这份可以直接抄把 apiKey 换成环境变量引用{ model: claude-sonnet-4-20250514, provider: { baseURL: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY} }, skills: { paths: [./skills], autoLoad: true }, request: { timeout: 120000, maxRetries: 2 } }几个参数说明一下。baseURL 填 TaoToken 的 API 地址不要带末尾斜杠。apiKey 用${TAOTOKEN_API_KEY}这种形式运行时从环境变量读。skills.paths 是技能搜索路径autoLoad 打开后新会话会自动加载技能。timeout 单位是毫秒技能里如果有长任务比如批量 Git 操作可以调到 180000。环境变量这样设Linux 和 macOS 写进 shell 配置export TAOTOKEN_API_KEYsk-你的KeyWindows PowerShell$env:TAOTOKEN_API_KEYsk-你的Key3.3 config.toml 骨架config.toml 管的是更底层的通道配置比如多 provider 切换、代理设置、日志级别。如果你只用 TaoToken 一个通道这份就够[default] provider taotoken log_level info [providers.taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY models [claude-sonnet-4-20250514, gpt-4o] [skills] root ./skills strict_validation truestrict_validation 打开后技能文件缺字段会在加载时报错而不是静默跳过。这个开关在技能多起来之后很有用能提前发现格式问题。log_level 调试阶段可以设成 debug稳定后改回 info不然日志会刷得很快。3.4 .gitignore 别漏.env *.local.json node_modules/ .DS_Store凭证文件、本地覆盖配置、依赖目录都不进版本库。技能本体和配置文件进 Git凭证走环境变量这条线要划清楚。4. 用 skill-creator 走完技能创建与迭代4.1 先执行一次真实任务skill-creator 的逻辑是「先做出来再总结成技能」所以第一步不是写文档而是在 Opencode 会话里真干一件事。我拿合并两个 Git 仓库当例子这个任务步骤多、有边界情况适合演示。进入项目目录打开 Opencode 会话输入合并当前文件夹下的两个仓库为一个仓库要求 1. 合并后使用 git pull 和 git push 就能完成推拉 2. 两个仓库的历史提交记录都要保留Opencode 会自己执行 git remote add、git fetch、git merge 这一串命令。跑完之后你手动验证三件事代码是否都在、git log --oneline是否能看到两边的历史、git push是否正常。验证通过再进下一步没通过就先修别急着固化技能。4.2 用 /skill-creator 提取技能同一个会话里直接调/skill-creator 请把本次仓库合并的方法总结为标准的技能它会分析刚才的执行过程在 skills 目录下生成 git-merge-repos/SKILL.md。生成完去目录里看一眼重点检查四样步骤顺序对不对、命令参数有没有写错、异常分支有没有覆盖、依赖说明清不清楚。如果你不想逐行读确认文件存在、技能名对剩下的交给后续测试来暴露问题。4.3 测试与迭代换一个新目录放两个测试仓库开新会话输入合并当前文件夹中的两个仓库观察它是否自动命中 git-merge-repos 技能。如果没命中检查 settings.json 里的 skills.paths 是否指向正确目录以及技能名和调用描述是否匹配。发现问题就在同一会话里继续改/skill-creator 分析使用 git-merge-repos 技能合并的过程改进 git-merge-repos 技能我实测下来最容易出问题的是目录命名。默认逻辑会把 mi-cop-front 改成 front但实际项目里目录名往往被脚本引用不能动。这时候补一条约束/skill-creator 我希望该技能在合并仓库时非必要不改变原文件夹名字 比如原文件夹是 mi-cop-front合并后还是 mi-cop-front不应该改为 front改完再换一个目录测重复三到五轮直到不同场景下都能稳定跑完、边界情况有处理、不需要你中途干预。技能自检可以单独开一个会话/skill-creator 进行 git-merge-repos 的检查它会扫逻辑漏洞、缺失步骤、命令错误和未处理的边界情况。自检结果当参考最终判断还是看实际执行。5. 验证请求确认通道和技能都生效配置写完、技能生成完要有一个明确的验证动作不然你不知道是配置没生效还是技能没命中。第一步验证 API 通道。用 curl 直接打 TaoToken 的接口确认 Key 和环境变量都对curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 ok}] }返回里能看到 content 字段和正常文本说明 Key 和地址没问题。如果返回 401检查环境变量有没有在当前 shell 生效返回 404检查 baseURL 是不是多写了路径。第二步验证技能加载。在 Opencode 会话里输入列出当前已加载的技能能看到 git-merge-repos 就说明 skills.paths 和 autoLoad 生效了。看不到就回到 settings.json 检查路径是相对路径还是绝对路径相对路径是相对于启动目录的这点容易搞错。第三步端到端验证。新开一个目录放两个仓库直接说「合并当前文件夹中的两个仓库」看它是否自动调用技能并完成。三步都过说明配置、通道、技能这条链路是通的。6. 把技能提交进 Git 做版本管理技能稳定之后就该进版本库了。这一步同样可以让 Opencode 代劳不用记 Git 命令请将本次新增的 git-merge-repos 技能提交到 Git 仓库它会依次执行 git status、git add、git commit如果配了远程还会 push。提交信息建议写清楚技能名和这次改了什么比如feat(skill): add git-merge-repos with history preservation。后面回滚和查历史都靠这个。手动操作的话就是这几条git add skills/git-merge-repos/ git commit -m feat(skill): add git-merge-repos with history preservation git push origin main版本管理带来的实际好处是回滚。技能改坏了git checkout HEAD~1 -- skills/git-merge-repos/就能退回上一版比手动备份靠谱。团队协作时别人 clone 仓库就能拿到你的技能配合各自的 TAOTOKEN_API_KEY 环境变量通道互不干扰。7. 本篇常见错排查技能不加载先看 settings.json 里 skills.paths 的路径。相对路径基于启动 Opencode 的目录不是配置文件所在目录。用绝对路径最稳。再看 SKILL.md 的头部字段是否完整strict_validation 打开时缺字段会直接报错。API 返回 401环境变量没生效。echo $TAOTOKEN_API_KEY确认有值没有就重新 source 一下 shell 配置。Windows 下注意 PowerShell 和 CMD 的环境变量语法不同。API 返回 404baseURL 写错了。正确值是https://taotoken.net/api不要加/v1后缀也不要加末尾斜杠具体路径由请求本身带。技能命中了但执行结果不对多半是技能文档里的命令参数和当前环境不匹配。回到会话里用/skill-creator改进把出错场景描述清楚比手动改文档更省事。Git 提交把 Key 带进去了立刻把 Key 从配置文件里删掉改成环境变量引用然后git rm --cached掉含 Key 的文件重新提交。已经推到远程的话去 TaoToken 控制台把那个 Key 吊销重新生成一个。合并仓库后目录名被改这是技能默认逻辑的问题用第 4 节的约束提示词补一条规则重新测试后再提交。8. 下一步把通道和技能都固定下来技能创建这件事跑通一次之后就是重复执行任务、提取技能、测试、改进、提交。真正省时间的是把配置固定下来让每次新会话都自动加载技能、自动走 TaoToken 通道。如果你主要做编码类任务想让 Opencode 长期稳定地调用模型可以看一下 Coding Plan 的接入方式它更适合高频使用场景。想先验证模型响应是否正常直接用模型对话入口发一条消息最快。需要管理多个 Key 或者查看调用情况去控制台和 API Keys 页面操作。配置细节和参数说明都在接入文档里遇到报错先查文档再排查环境变量。把 settings.json 和 config.toml 提交进仓库把 Key 留在环境变量里把技能当代码一样迭代。这套流程跑顺之后你积累的就不只是几个技能文件而是一个能持续复用的个人技能库。