1. 从一次「三端配置漂移」说起
Agent Skill 这件事，真正让人头疼的不是写第一版，而是写到第三版之后：Claude Code 里已经修好的触发描述，Codex 那边还是旧文案；本地跑通的脚本，换台机器路径又不对。我试过把同一份 SKILL.md 复制到三个目录，结果两周后自己都分不清哪份是最新的。
这篇要解决的就是这个问题：手搓一个可复用的 Agent-Skill，用 TaoToken 统一 Key 打通 Claude Code 与 Codex，做到一次编写、多工具复用。核心交付物有三样：一份可直接复制的 SKILL.md 骨架、settings.json 与 config.toml 里接入 TaoToken 统一 API 通道的配置片段、以及调用验证与排错动作。
适合谁看：已经在用 Claude Code 或 Codex、想让重复流程沉淀成技能包的开发者；被多端配置不一致折磨过的人；以及想给团队做一套共享 Skill 仓库的技术负责人。不需要先学 SDK，Markdown 加一份配置文件就够。
Skill 的本质，可以理解成「给 Agent 的专项操作手册」。它和传统 Prompt 的区别在于：Prompt 每次对话重新粘贴，Skill 写一次长期复用；Prompt 靠人记得提，Skill 靠 description 自动匹配触发；Prompt 难协作，Skill 可以进仓库团队共享。完整工作流是四步：安装（把目录放到约定路径）、发现（启动时只读 frontmatter 的 name 和 description）、触发（用户说相关需求或显式调用）、执行（读入完整 SKILL.md，必要时再读引用文件或跑脚本）。这就是渐进式披露——先轻量索引，需要时再展开，避免把上下文窗口一次性塞满。
2. TaoToken 前置：一把 Key 打通两个工具
多工具复用最大的摩擦点其实不在 Skill 格式，而在模型通道。Claude Code 默认走 Anthropic 的接口，Codex 走 OpenAI 的接口，两套 Key、两套计费、两套环境变量。如果每个工具都要单独配一遍，Skill 复用的收益会被配置成本吃掉。
TaoToken 在这里扮演的角色是统一入口：一个 Key、一个 API 地址，同时兼容 Anthropic 与 OpenAI 两种协议风格。你可以在官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 了解整体能力，实际接入只需要记住 API 根地址是 https://taotoken.net/api（这个地址不加 UTM 参数，直接写进配置文件）。
需要提前准备的东西不多：一个 TaoToken 账号、一把 API Key、本机装好 Claude Code 与 Codex CLI。Key 的创建入口在控制台的 API Keys 页面，建议按工具分 Key，比如claude-code-key和codex-key各一把，这样出问题时能快速定位是哪个工具在异常调用，也方便单独吊销。
注意：Key 只显示一次，创建后立刻复制到密码管理器。不要写进会提交到 Git 的配置文件里，用环境变量或本地未跟踪的配置文件承载。
关于计费与额度，控制台里有独立的用量视图，可以按 Key 维度看调用量。如果你打算长期跑编码类 Agent 任务，Coding Plan 这类包月方案通常比按量更划算，具体档位以官网当前页面为准，这里不编造价格。
3. 可复制配置：SKILL.md 骨架 + 双工具接入
3.1 目录结构与 SKILL.md 骨架
最小可运行形态就是一个目录加一个 SKILL.md：
commit-helper/ ├── SKILL.md # 必填：元数据 + 指令 ├── references/ # 可选：细则、对照表 ├── scripts/ # 可选：校验/转换脚本 └── assets/ # 可选：模板、样例文件SKILL.md 固定两段结构，上半部分是 YAML frontmatter，下半部分是正文。直接复制这份骨架改：
--- name: commit-helper description: 根据 git diff 生成规范提交说明。在用户提到提交、commit message、写提交信息、整理变更摘要时使用。 --- # Commit Helper ## 何时启用 - 用户要求写提交信息、整理变更摘要 - 用户贴出 git diff 并询问如何描述 - 不要用于：代码审查、性能优化建议（防误召） ## 强制流程 1. 执行 `git diff --staged` 查看暂存区改动 2. 若暂存区为空，改看 `git diff` 并提示用户先 add 3. 按约定格式写标题与正文 4. 指出风险点：机密信息、破坏性操作、大文件 ## 输出格式 feat(scope): 一句话说明 为什么改；影响范围（可选） ## 验收清单 - [ ] 标题不超过 72 字符 - [ ] 类型前缀在 feat/fix/docs/refactor/test/chore 之内 - [ ] 正文说明了「为什么」而不只是「做了什么」 ## 需要时再读 - 字段对照：[references/field-map.md](references/field-map.md) ## 脚本（如有） - 校验：`python scripts/validate.py <path>`frontmatter 里两个字段是发现机制的全部：name用小写、数字、连字符，尽量短且可念可搜，commit-helper合格，helper、utils、tmp不合格；description必须同时写清做什么（WHAT）和何时用（WHEN），用第三人称，把用户常说的词写进去当触发词。「帮助处理文档」这种写法太空，模型不知道何时加载；「从 PDF 提取文本与表格、合并页面。在用户提到 PDF、表单填写、文档抽取时使用」才是合格的产品入口。
3.2 Claude Code 接入 TaoToken
Claude Code 的配置走settings.json，位置通常在~/.claude/settings.json（个人全局）或项目内.claude/settings.json。核心是把 API 根地址指向 TaoToken，并用环境变量注入 Key：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-your-taotoken-key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }如果你不想把 Key 明文写进 settings.json，可以只保留ANTHROPIC_BASE_URL，然后在 shell 启动文件里导出ANTHROPIC_AUTH_TOKEN。两种方式都行，团队共享的仓库里推荐后者。
Skill 的放置路径：
| 范围 | 路径 |
|---|---|
| 个人全局 | ~/.claude/skills/<skill-name>/SKILL.md |
| 当前仓库 | .claude/skills/<skill-name>/SKILL.md |
唤起方式有两种：自动匹配靠 description，手动调用用/skill-name，目录名通常就是命令名。
3.3 Codex 接入 TaoToken
Codex 的配置走config.toml，位置一般在~/.codex/config.toml。TaoToken 兼容 OpenAI 协议风格，所以配置项是base_url加env_key：
model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api/v1" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"然后在 shell 里导出：
export TAOTOKEN_API_KEY="sk-your-taotoken-key"Skill 的放置路径：
| 范围 | 路径 |
|---|---|
| 个人 | ~/.agents/skills/<skill-name>/ |
| 仓库 | .agents/skills/<skill-name>/ |
Codex 同样靠 name 加 description 做发现，完整正文按需加载。仓库里如果还有AGENTS.md，它更像项目总规矩，Skill 更像可插拔专项流程，两者互补，不要把细节全塞进一个文件。
3.4 单源加软链，避免三份漂移
三端目录不同，但内容可以只有一份真源：
~/agent-skills/ └── commit-helper/ ├── SKILL.md ├── references/ └── scripts/然后在各工具目录做符号链接：
ln -s ~/agent-skills/commit-helper ~/.claude/skills/commit-helper ln -s ~/agent-skills/commit-helper ~/.agents/skills/commit-helperWindows 用开发者模式下的mklink /J做目录联接。这样改一处三端同步，不会出现「Claude 版修了、Codex 版还是旧文案」。团队进 Git 时，把真源放仓库的skills/目录，各工具目录用相对路径软链，比复制三份稳得多。
4. 验证请求：确认 Skill 真的被加载
配置写完别急着写第二个 Skill，先验证通道和发现机制都通了。
第一步验证 API 通道。用 curl 直接打 TaoToken 的接口，确认 Key 有效：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5-codex", "messages": [{"role": "user", "content": "reply with ok"}] }'返回里带choices字段就说明通道正常。如果返回 401，是 Key 问题；返回 404，多半是 base_url 少了或多了/v1，对照上面两段配置检查。
第二步验证 Skill 被发现。在 Claude Code 里输入/看命令列表里有没有commit-helper；在 Codex 里用$commit-helper或打开 skills 面板确认。列表里没有，说明目录放错了或 frontmatter 格式有问题。
第三步验证触发。准备一个真实场景，比如改完代码后直接说「帮我写个提交信息」，看 Agent 是否自动加载了 Skill 并按模板输出。再测一次显式调用，最后测一次边界请求——比如问「这段代码性能怎么样」，确认它不会误召 commit-helper。
三种触发都过了，这个 Skill 才算能用。误召和漏召的调参，大半发生在 description 的措辞上，而不是正文。
5. 本篇常见错排查
Skill 明明写了却从不触发。九成是 description 的问题：缺触发词、写得太像内部黑话、WHAT 有了 WHEN 没有。把它当成应用商店的一句话介绍重写，把用户真实会说的词补进去。
Claude Code 报连接错误。检查ANTHROPIC_BASE_URL是不是写成了带/v1的地址。Anthropic 协议风格的根地址是https://taotoken.net/api，不要自己加后缀。
Codex 报 404 或 model not found。检查base_url是不是https://taotoken.net/api/v1，以及model字段的名字是否在 TaoToken 支持的模型列表里。模型名写错不会报「模型不存在」，而是直接 404，容易误判成地址问题。
软链建了但工具读不到。有些工具在启动时做目录扫描，软链指向的目录如果权限不对会被跳过。用ls -la确认链接目标存在且可读，Windows 下确认用的是目录联接而不是文件快捷方式。
改了 SKILL.md 但行为没变。多数工具在会话启动时加载 Skill 索引，改完要重启会话。另外确认你改的是真源目录，不是某个工具目录下的副本。
多端行为不一致。大概率是某端还在读旧副本。回到单源加软链的方案，删掉所有复制出来的目录，只保留链接。
6. 把 Skill 写「好用」的几条硬经验
上下文很贵，废话很贵。默认假设模型已经很强，只写它不知道、且做错代价高的信息：你们的命名规范、验收闸门、禁止事项、输出模板。
自由度要匹配任务脆弱度。风格类任务（文案、评审意见）给原则加样例就够；结构类任务（报告、变更说明）给模板；高风险类任务（发布、迁移、批量改库）必须给逐步清单加脚本校验加明确停止条件。
先给默认路径，少给平行选项。「你可以用 A，也可以 B，也可以 C」会让模型漂移；「默认用 A，仅当出现 X 情况时改用 B」才稳。术语全文只留一套，不要混用「提交说明」「变更摘要」「PR 描述」三个近义词。
上线前花十分钟自检：name 合法且好记、description 含 WHAT 加 WHEN 加触发词、主文件短且细则外置、有输出模板或检查清单、禁止事项写清楚、路径用正斜杠相对路径、在目标工具目录放对位置、测过自动触发加手动触发加误触发、多端使用时确认只有一份真源。
挑一个你每周至少说三遍的流程，手搓第一个 SKILL.md。通道配置和排错动作上面都给全了，剩下的就是动手。需要看模型实际表现时，可以直接在模型对话里试；长期跑编码和 Agent 任务，用 Coding Plan 更省心；Key 管理和用量查看在控制台的 API Keys 页面；接入细节有疑问翻接入文档。
