1. 为什么你的 Agent 总是“记不住事”从上下文爆炸说起如果你最近在折腾 OpenCode 或者 Claude Code大概率听过一个词Agent Skill。简单说它是把 Agent 的某一种能力做成“可插拔的模块”让模型在需要的时候才去翻那本厚厚的说明书而不是一上来就把所有工具文档全塞进上下文。它适合谁适合那些已经用上命令行 Agent、但被“上下文爆炸”折磨过的开发者——每次对话都要重复贴 API 格式、反复纠正输出结构、工具一多模型就开始胡言乱语。我自己的体感是传统做法里 Prompt 像入职培训手册Tools 像办公文具而 Skill 更像职业技能认证平时不占地方真到报销的时候才去翻那本财务软件操作手册。这背后是“渐进式披露”的思路——Agent 先只看到一份极简的技能索引只有当它判断“这个任务需要用到 PDF 解析”时才把SKILL.md以及同目录下的脚本、模板、参考文档加载进来。这样一来初始 token 消耗能从动辄上万降到几百模型的注意力也不会被无关工具定义稀释。但问题来了Skill 要跑起来底层得有一个稳定的模型通道。OpenCode 默认给了一批免费模型可一旦你要接 Claude Code 那套 Skill 生态或者想在自己的渐进式智能体里统一管理 Key就会遇到多工具、多 Key、多 Base URL 的混乱。这篇就围绕这个痛点用 TaoToken 做统一 Key/API 通道带你把第一个 Skill 从零创建出来并在 OpenCode 与 Claude Code 之间用 CC Switch 验证切换。2. 前置准备用 TaoToken 统一 Key 与 API 通道在动手写 Skill 之前先把“路”修好。Agent Skill 本身不绑定某一家模型但 Claude Code 的 Skill 规范目前最成熟而 OpenCode 作为开源替代对 Skill 的加载机制也兼容得不错。为了让两个工具共用一套凭证我建议用 TaoToken 作为统一入口官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM直接填进配置里。你需要先拿到一个 API Key。登录后进控制台在 API Keys 页面创建一个新 Key复制出来备用。这里注意Key 只显示一次丢了就重新生成。TaoToken 的通道兼容 Anthropic 与 OpenAI 两种协议风格所以 OpenCode 和 Claude Code 都能直接对接不用为每个工具单独申请账号。提示不要把 Key 硬编码进 Skill 的SKILL.md里。Skill 是会被分享和复用的Key 应该放在工具自己的配置文件或环境变量中Skill 只负责逻辑。如果你还没决定用哪个工具可以先想清楚OpenCode 胜在开源、跨平台、有免费模型兜底Claude Code 胜在 Skill 生态和渐进式披露的实现最完整。两者都支持通过自定义 Base URL 接入第三方通道这正是 TaoToken 的用武之地。3. 可复制配置settings.json 与 config.toml 双通道接下来是核心的配置环节。OpenCode 和 Claude Code 的配置文件格式不同我分别给出可复制的片段。你只需要把你的_TaoToken_Key替换成上一步拿到的真实 Key。3.1 Claude Code 的 settings.jsonClaude Code 读取的是用户目录下的~/.claude/settings.json。如果你想让 Skill 走 TaoToken 通道重点是设置env里的ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Bash ] } }这里ANTHROPIC_MODEL可以按你实际订阅的模型名调整。permissions.allow决定了 Skill 里脚本能调用哪些工具初期建议只开 Read/Write/Bash跑通后再按需放开。3.2 OpenCode 的 config.tomlOpenCode 的配置通常在~/.config/opencode/config.toml。它支持自定义 provider我们把 TaoToken 作为一个 OpenAI 兼容的 provider 写进去[provider.taotoken] name TaoToken baseURL https://taotoken.net/api apiKey 你的_TaoToken_Key [model] provider taotoken name claude-sonnet-4-20250514 [skill] enabled true paths [~/.opencode/skills]skill.paths指向你存放 Skill 的目录。OpenCode 启动时会扫描这个目录下的每个子文件夹读取其中的SKILL.md作为技能索引。注意baseURL后面不要多加/v1TaoToken 的 API 根路径已经处理好了。3.3 CC Switch 切换验证如果你同时装了 Claude Code 和 OpenCode可以用 CC Switch 这类配置切换工具在“TaoToken 通道”和“官方通道”之间快速切换。切换后执行一次claude --version或opencode --version确认工具能正常启动再进下一步。这一步的目的是排除“配置写错但没发现”的情况别等到 Skill 加载失败才回头查。4. 创建第一个 Skill从 SKILL.md 到渐进式加载配置通了现在正式创建 Skill。我们做一个最实用的根据书名生成拆书笔记的 Canvas 文件。这个 Skill 会演示“渐进式披露”的两个层次——主文件只写触发条件和流程详细模板放在同目录的template.md里只有真正生成笔记时才加载。4.1 目录结构在~/.opencode/skills下新建一个文件夹book-canvas结构如下book-canvas/ ├── SKILL.md # 主技能文件含 frontmatter 与流程 ├── template.md # Canvas 模板按需加载 └── scripts/ └── gen_canvas.py # 生成 canvas 的脚本4.2 SKILL.md 的 frontmatterSKILL.md开头必须有一段 YAML frontmatter这是 Agent 做“技能索引”时唯一会预先读取的部分。所以描述要短、准、能触发--- name: book-canvas description: 根据书名生成拆书笔记 Canvas包含核心观点、章节脉络与行动清单 trigger: 当用户要求为某本书创建拆书笔记或 Canvas 时使用 --- # 拆书笔记 Skill ## 执行流程 1. 从用户输入中提取书名。 2. 读取 template.md 获取 Canvas 结构。 3. 调用 scripts/gen_canvas.py 生成 .canvas 文件。 4. 将生成路径返回给用户。 ## 资源引用 - 模板文件template.md仅在生成笔记时加载。 - 生成脚本scripts/gen_canvas.py通过 Bash 执行。注意description和trigger是给 Agent 看的不是给人看的。写得越具体Agent 越容易在正确时机命中这个 Skill。4.3 template.md 与脚本template.md里放 Canvas 的节点结构比如# Canvas 模板 - 中心节点书名 - 分支一核心观点3-5 条 - 分支二章节脉络按时间或逻辑 - 分支三行动清单可执行项scripts/gen_canvas.py负责把模板和模型生成的内容拼成 JSON Canvas 格式import json import sys def build_canvas(book, points): nodes [{id: root, type: text, text: book, x: 0, y: 0}] for i, p in enumerate(points): nodes.append({ id: fn{i}, type: text, text: p, x: 300, y: i * 150 }) return {nodes: nodes, edges: []} if __name__ __main__: book sys.argv[1] points sys.argv[2:] canvas build_canvas(book, points) with open(f{book}.canvas, w, encodingutf-8) as f: json.dump(canvas, f, ensure_asciiFalse, indent2) print(f已生成 {book}.canvas)这个脚本就是 Skill 里“确定性执行”的体现——格式解析交给代码模型只负责内容生成避免幻觉。4.4 在 OpenCode 中触发重启 OpenCode输入请帮我为《人类简史》创建一个拆书笔记 CanvasAgent 会先匹配到book-canvas的 trigger然后加载SKILL.md再按流程读取template.md、执行脚本。你会在当前目录看到人类简史.canvas。整个过程里template.md和脚本只有在命中 Skill 后才被加载这就是渐进式披露的实际效果。5. 本篇常见错排查跑不通的时候按下面顺序查基本能覆盖九成问题。Skill 没被触发。先看SKILL.md的 frontmatter 是否合法YAML 对缩进敏感description里不要有冒号后跟空格。再看skill.paths是否指向了正确的父目录OpenCode 只扫描一级子文件夹。401 或 403 报错。说明 Key 或 Base URL 有问题。检查settings.json里ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api末尾不要带斜杠。OpenCode 的config.toml里apiKey是否被引号包裹。如果刚生成 Key等几秒再试权限同步有延迟。脚本执行失败。多半是permissions.allow没开 Bash或者脚本没有执行权限。在终端里手动跑一次python scripts/gen_canvas.py 测试 观点1确认脚本本身没问题。另外注意脚本里的路径是相对 Skill 目录还是当前工作目录建议用绝对路径或os.path.dirname(__file__)。模型返回格式不对。如果 Agent 没有按template.md的结构输出检查SKILL.md里是否明确写了“读取 template.md”。有些模型会偷懒跳过资源加载你可以在流程里加一句“必须读取模板后再生成”。切换工具后 Skill 失效。Claude Code 和 OpenCode 的 Skill 目录不同Claude Code 默认读~/.claude/skills。用 CC Switch 切换后确认目标工具的 Skill 路径下确实有你的book-canvas文件夹。6. 把通道固定下来让 Skill 真正可复用走到这里你已经有了一个能跑的 Skill也有了统一的 Key 通道。接下来最值得做的一件事是把 TaoToken 的接入方式固化到你的日常流程里需要排障或接入新工具时直接去 API Keys 页面生成专用 Key再对照接入文档填配置想快速验证模型是否正常用模型对话页面发一条测试消息如果你打算长期用 Agent 做编码或自动化Coding Plan 会比按次调用更省心。Skill 的价值不在于写一个两个而在于积累。每当你发现自己又在重复贴同一段 API 格式、同一套输出规范就把它抽成一个 Skill。通道统一之后这些 Skill 在 OpenCode 和 Claude Code 之间迁移的成本会低很多。我自己的习惯是每完成一个项目就把其中可复用的流程写成SKILL.md模板和脚本放同目录下次直接复制文件夹。这样攒下来的不是提示词而是一套真正属于你的渐进式智能体能力库。