1. Windows 下 opencode 添加 skills 的真实痛点如果你在 Windows 上用 opencode 做日常编码大概率会遇到一个很别扭的问题skills 明明下载好了放进目录却死活不加载或者这个项目能用的 skill换个项目又得重新配一遍。更麻烦的是 Key 管理——opencode 要一份、别的 CLI 工具要一份、临时脚本又要一份散落在各个 config 文件里改一次要翻好几个地方。opencode 的 skills 机制本身不复杂它就是在约定目录里扫描 skill 定义文件然后把这些能力挂到当前会话上。真正让人踩坑的是 Windows 的目录约定项目级目录和用户级目录是两套路径AppData\Local和AppData\Roaming又容易搞混很多人复制完发现没生效其实是放错了层级。这篇就聚焦 Windows 环境下给 opencode 添加 skills 的完整流程顺带把多工具 Key 分散的问题一起解决掉——用 TaoToken 的统一 Key 接入一次配置opencode 里稳定调用 skills。适合谁看已经在 Windows 上装了 opencode、想加自定义 skill 但没跑通的手里有多个 AI 编码工具、被 Key 管理搞烦的以及想搞清楚 skills 目录到底该放哪的人。下面从目录结构讲起给出可复制的配置骨架最后用一次真实请求验证 skills 是否加载成功。2. 先理清 opencode 的 skills 目录与 TaoToken 统一 Keyopencode 在 Windows 上找 skills会按优先级扫描几个位置。项目级优先于用户级这样你可以给单个项目定制 skill又不影响全局。实测下来下面这几个路径是它真正会读的层级路径适用场景项目级D:\code_cys\nsfc-main2026\.opencode\skills只给当前项目用随仓库走用户级 LocalC:\Users\你的用户名\AppData\Local\opencode\skills当前用户所有项目共享用户级 RoamingC:\Users\你的用户名\AppData\Roaming\opencode\skills漫游配置多机同步时用项目级目录就是「当前项目根目录下的.opencode\skills」。注意是项目根目录不是随便哪个子目录。你把 skill 文件夹复制进去之后opencode 启动时会自动扫描这个目录下的每个子目录每个子目录里应该有一个 skill 定义文件通常是SKILL.md或类似的清单文件。用户级两个目录的区别Local是本机专用Roaming会跟着 Windows 账户漫游。如果你只有一台机器放Local就够了如果公司配了域账户、多台设备同步放Roaming更省事。两个目录都放的话opencode 会都扫但同名 skill 可能产生覆盖建议只保留一处。Key 这块opencode 支持通过环境变量或配置文件读取 API Key。与其给每个工具单独配一份不如用 TaoToken 的统一 Key在 TaoToken 控制台生成一个 Key然后让 opencode 通过环境变量引用它。这样你换工具、加工具Key 只维护一份。TaoToken 的 API 入口是https://taotoken.net/api兼容常见的 OpenAI 风格调用opencode 这类工具接起来很顺。注意skills 目录里放的是能力定义不是可执行程序。别把.exe或脚本直接丢进去当 skillopencode 不会执行它只会读定义文件。3. 可复制的 settings.json 与 config.toml 骨架opencode 在 Windows 上的配置分两块一块是工具本身的设置模型、Key 来源一块是 skills 的加载路径。下面给出可直接改的骨架。先看settings.json放在用户配置目录下通常是C:\Users\你的用户名\.opencode\settings.json如果不存在就新建{ model: claude-sonnet-4-20250514, provider: { baseURL: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY }, skills: { enabled: true, paths: [ D:\\code_cys\\nsfc-main2026\\.opencode\\skills, C:\\Users\\你的用户名\\AppData\\Local\\opencode\\skills ] } }几个关键点baseURL指向 TaoToken 的 API 地址apiKeyEnv表示 Key 从环境变量TAOTOKEN_API_KEY读取这样配置文件里不出现明文 Key安全也方便换。skills.paths里用双反斜杠转义Windows 路径必须这么写单反斜杠会被 JSON 解析成转义字符。再看config.toml如果你用的是 TOML 风格的配置部分 opencode 版本或插件会读这个[provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [skills] enabled true paths [ D:\\code_cys\\nsfc-main2026\\.opencode\\skills, C:\\Users\\你的用户名\\AppData\\Local\\opencode\\skills ]TOML 里反斜杠同样要转义或者干脆用正斜杠D:/code_cys/nsfc-main2026/.opencode/skillsWindows 下正斜杠也能识别省得数反斜杠。环境变量设置在 PowerShell 里执行当前会话生效$env:TAOTOKEN_API_KEY 你的TaoToken Key想永久生效用系统环境变量[Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的TaoToken Key, User)设置完记得重开一个终端让新环境变量加载进去。Key 在 TaoToken 控制台的 API Keys 页面生成生成后只显示一次复制好再关页面。4. 验证 skills 加载与请求成功配置写完怎么确认 skills 真的加载了分两步先看 opencode 启动日志再发一次真实请求。第一步在项目目录下启动 opencode观察输出。正常加载时会打印扫描到的 skills 数量和路径类似[skills] scanning D:\code_cys\nsfc-main2026\.opencode\skills [skills] loaded 3 skill(s): code-review, doc-gen, sql-helper如果只看到scanning没有loaded说明目录扫到了但没解析出 skill多半是 skill 定义文件格式不对或文件名不对。第二步发一次请求验证模型和 Key 都通。在 opencode 会话里输入一个简单任务比如让它调用某个 skill用 code-review skill 检查一下当前目录的 main.py如果返回了正常的审查结果说明三件事都成了TaoToken 的 Key 有效、模型调用通、skill 被正确挂载。如果返回鉴权错误是 Key 或环境变量的问题如果返回「未知 skill」是 skills 路径或定义文件的问题。你也可以直接用 curl 验证 TaoToken 的 API 通不通排除 opencode 本身的干扰curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:ping}]}返回里有正常的choices字段就说明 Key 和网络都没问题剩下的问题都在 opencode 配置侧。5. 本篇常见错误排查skills 不加载日志里连 scanning 都没有。八成是skills.paths没配对或者enabled是 false。检查 JSON 里路径的双反斜杠有没有写错Windows 路径写错一个字符就整个失效。另外确认你改的是 opencode 真正读取的那个配置文件有些版本读settings.json有些读config.toml两个都放一份最稳。日志显示 scanning 但 loaded 为 0。目录对了但 skill 定义文件没被识别。检查每个 skill 子目录里是否有正确的定义文件文件名大小写敏感Windows 默认不敏感但 opencode 内部可能按 Linux 规则处理。把 skill 目录结构贴出来对照应该是skills\code-review\SKILL.md这种而不是skills\code-review.md。Key 报鉴权失败。先确认环境变量在当前终端里能读到echo $env:TAOTOKEN_API_KEY。如果为空是环境变量没生效重开终端或改用系统级设置。如果 Key 有值还报错检查baseURL是不是https://taotoken.net/api末尾不要多加/v1opencode 会自己拼路径。项目级 skill 和用户级 skill 冲突。同名 skill 在两处都存在时行为不确定。建议项目专用的放项目目录通用的放用户目录命名上区分开比如proj-code-review和global-code-review。路径里有中文或空格。Windows 用户名带中文、项目路径带空格都可能导致扫描失败。尽量把项目放在纯英文无空格路径下比如D:\code\cys\nsfc-main2026。6. 一次配置长期稳定调用把 Key 收敛到 TaoToken 一处之后opencode 的配置就只剩 skills 路径这一件事要维护。项目级的 skill 跟着仓库走用户级的 skill 一次配好全局可用换项目不用重配 Key加新工具也只是多引用一次同一个环境变量。如果你还在被多个工具的 Key 分散困扰建议先把 opencode 这条链路跑通在 TaoToken 控制台生成 Key配好环境变量把 skills 目录指对然后用一次真实请求验证。跑通之后再把这套 Key 引用方式复制到其他工具上维护成本会明显下降。需要生成 Key 的话去 TaoToken 控制台的 API Keys 页面接入细节和参数说明看接入文档想先验证模型通不通可以直接用模型对话试一条如果是要长期跑编码和 Agent 任务Coding Plan 更适合持续调用。