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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=API 基地址单独记一下，配置里要填的就是它，注意这个地址不带跟踪参数：
https://taotoken.net/api拿到 Key 的路径是控制台里的 API Keys 页面，创建后复制那串以 sk- 开头的字符串，只显示一次，先存到密码管理器里。后面 settings.json 和 config.toml 都会用到它。
注意：Key 不要直接写进会提交到 Git 的配置文件。技能仓库是公开或团队共享的，凭证一旦进版本历史就很难彻底清除。用环境变量引用，配置文件里只留变量名。
如果你后面要长期跑编码类任务或者 Agent 流程，可以顺带看一下 Coding Plan 的说明，它和按量调用是两种计费思路，选哪个取决于你的使用频率。模型对话入口可以用来快速验证 Key 是否有效，不用写代码就能发一条测试请求。
3. 可复制配置：技能目录、settings.json 与 config.toml
3.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_KEY="sk-你的Key"Windows PowerShell：
$env:TAOTOKEN_API_KEY="sk-你的Key"3.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 返回 404：baseURL 写错了。正确值是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 留在环境变量里，把技能当代码一样迭代。这套流程跑顺之后，你积累的就不只是几个技能文件，而是一个能持续复用的个人技能库。
