1. 为什么 SKILL.md 值得单独拿出来讲
如果你已经在用 Claude Code 或者 Codex 写代码，大概率遇到过这种情况：模型很能写，但写着写着就跑偏了。你让它加个过滤功能，它顺手把状态管理重构了一遍；你让它修个 bug，它给你换了个框架。问题不在模型能力，而在于你从来没告诉它「按什么流程干活」。
mattpocock/skills 这个仓库解决的就是这件事。它不是往上下文里塞一大坨 prompt，而是把工程实践拆成一组小而明确的技能文件，每个技能就是一个 SKILL.md。你可以把它理解成给 AI 编程助手装了一套「默认工作纪律」：先澄清需求，再设计，再 TDD，再诊断，最后收尾。
SKILL.md 是这套机制的核心载体。它本质上是一个带 YAML frontmatter 的 Markdown 文件，放在特定目录下，AI 编程助手启动时会扫描这些文件，把技能注册成可调用的命令。Claude Code 走的是.claude/skills/目录，Codex 走的是~/.codex/skills/或项目级.codex/skills/。目录放对了，重启工具，技能就能用/技能名的方式触发。
这篇文章面向的是想快速跑通第一个技能示例的人。我会给出可复制的目录结构、SKILL.md 配置片段、一次完整的调用验证动作，以及怎么通过 TaoToken 统一 Key 和 API 通道完成模型侧接入。不绕弯子，直接上手。
2. SKILL.md 结构解析与 mattpocock/skills 安装路径
先说 SKILL.md 到底长什么样。一个标准的技能文件由两部分组成：顶部的 YAML frontmatter 和下面的 Markdown 正文。frontmatter 里至少要写name和description，name决定你调用时敲什么命令，description决定模型什么时候会主动想起这个技能。
--- name: tdd description: 红绿重构工作流。当用户要求实现新功能或修复 bug 时使用，先写失败测试，再写最小实现，最后重构。 --- # TDD 技能 ## 工作流程 1. 先写一个失败的测试，证明目标行为尚未实现 2. 运行测试，确认它确实失败 3. 写最小实现让测试通过 4. 在测试保护下重构 5. 重复上述步骤 ## 约束 - 不允许在没有失败测试的情况下写实现代码 - 每次只处理一个行为 - 测试通过前不重构这个结构看起来简单，但有几个坑要注意。name只能用字母、数字和连字符，不能用中文或空格。description要写清楚「什么时候用」，而不是「这是什么」，因为模型是靠 description 做技能路由的。正文部分建议用步骤化的写法，模型执行时更稳。
mattpocock/skills 仓库里的技能都遵循这个结构。仓库里比较常用的几个技能包括：grill-me负责先把需求问清楚，grill-with-docs在澄清需求时顺便建立项目语言和文档，tdd走红绿重构，diagnose做系统化排查，to-prd把上下文整理成 PRD，zoom-out先看全局再看局部，improve-codebase-architecture收敛面条化代码库，setup-matt-pocock-skills给当前仓库做基础配置。
安装方式分两条路。Claude Code 和部分支持 skills 协议的工具可以用 npx 一键安装：
npx skills@latest add mattpocock/skills执行后工具会交互式问你两个问题：要安装哪些 skills，要装到哪个 coding agent。这里有个关键点，一定要把setup-matt-pocock-skills一起选上。后面很多工程类技能都依赖它先把仓库级配置补齐，比如 issue tracker 用哪个、triage 时打什么标签、生成的文档放哪里。没有这层配置，to-issues、triage、diagnose这些技能会变成「看起来能用，实际上上下文不统一」。
Codex 不走 npx 一键安装，而是手动把需要的 SKILL.md 复制到对应目录。Codex 的技能目录是~/.codex/skills/（全局）或项目根目录下的.codex/skills/（项目级）。复制完重启 Codex 生效。你也可以直接给 Codex 发提示词让它自己装：
安装技能 https://github.com/mattpocock/skills 到 codex 中如果你不想一次装全套，可以只装单个技能：
npx skills@latest add mattpocock/skills/tdd npx skills@latest add mattpocock/skills/diagnose建议先从setup-matt-pocock-skills、grill-me、tdd这三个开始，别一口气把全部流程塞进去。装太多技能反而会让模型在路由时犹豫。
3. 可复制配置：SKILL.md 目录结构与 TaoToken 接入片段
这一节给你可以直接抄的配置。先看目录结构，Claude Code 和 Codex 的路径不一样，别放错。
Claude Code 项目级技能目录：
your-project/ ├── .claude/ │ └── skills/ │ ├── setup-matt-pocock-skills/ │ │ └── SKILL.md │ ├── grill-me/ │ │ └── SKILL.md │ ├── tdd/ │ │ └── SKILL.md │ └── diagnose/ │ └── SKILL.md ├── src/ └── package.jsonCodex 项目级技能目录：
your-project/ ├── .codex/ │ └── skills/ │ ├── grill-me/ │ │ └── SKILL.md │ └── tdd/ │ └── SKILL.md ├── src/ └── package.json注意每个技能是独立子目录，SKILL.md 放在子目录里，不是直接堆在 skills 根目录下。这个层级关系搞错的话，工具扫描不到。
接下来是模型侧接入。Claude Code 和 Codex 都需要一个 API 通道来调用模型，TaoToken 提供统一的 Key 和 Base URL，省得你在多个工具之间来回切换配置。Claude Code 的配置文件在~/.claude/settings.json，写入以下内容：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "你的TaoToken Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }Codex 的配置走~/.codex/auth.json和~/.codex/config.toml两个文件。auth.json存 Key：
{ "OPENAI_API_KEY": "你的TaoToken Key" }config.toml指定 Base URL 和模型：
model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" wire_api = "responses"三件套要写全：Base URL、Key、Model ID。少任何一个都会在请求时报错。Key 在 TaoToken 控制台的 API Keys 页面生成，生成后复制到上面两个配置里。模型 ID 根据你实际用的模型填，Claude 系列和 GPT 系列都支持。
如果你用的是 Cline 或者带 MCP 的工具，配置逻辑一样，把 Base URL 指向https://taotoken.net/api，Key 填 TaoToken 的 Key，Model ID 填你要用的模型。Cline 的 MCP 配置里，provider 选 OpenAI Compatible，Base URL 和 Key 按上面填。
配置改完记得重启工具。Claude Code 和 Codex 都是启动时读配置，热改不生效。
4. 验证请求：跑通第一个技能调用
配置写完了，得验证一下到底通没通。分两步走：先验证模型通道，再验证技能调用。
先验证模型通道。在 Claude Code 里直接发一句话：
你好，请回复"通道正常"四个字如果返回了「通道正常」，说明 Base URL 和 Key 都对了。如果报 401，说明 Key 有问题；如果报连接失败，说明 Base URL 写错了。这一步过了再往下走。
接着验证技能是否注册成功。在 Claude Code 里输入/，看补全列表里有没有setup-matt-pocock-skills、grill-me、tdd这些命令。有的话说明 SKILL.md 被正确扫描到了。Codex 里输入/skills可以列出已注册的技能。
然后跑一次完整调用。用一个最小的 todo 项目演示。先执行初始化技能：
/setup-matt-pocock-skills它会问你几个基础问题：issue tracker 用 GitHub、Linear 还是本地文件；triage 时给 issue 打什么标签；生成的文档存放在哪里。按你的实际情况回答。这一步的价值在于把仓库的工作方式固定下来，后面to-issues、triage、diagnose都会直接吃这些约定。
初始化完成后，切到需求澄清技能：
/grill-me然后说清楚你的目标：
我要做一个 todo 应用，先实现新增、完成、过滤三个能力。 请先问我实现前必须确认的问题，不要直接写代码。这一步会逼着你把默认没想清楚的东西补上。比如数据要不要持久化、完成态怎么存、过滤支持哪些视图、新增输入要不要做空白处理、列表排序按什么规则、每条 todo 的唯一标识怎么生成。这些问题在写代码之前问清楚，比写完再改省事得多。
需求确认完，切到 TDD 技能：
/tdd引导它先写失败测试：
先写一个失败测试，证明 todo 列表初始为空； 再写一个测试，证明用户可以新增一个任务； 最后再实现完成状态和过滤逻辑。这样做的好处是 AI 不会一开始就把三个功能一起糊出来，每一步都有测试兜底，后面更容易逐步验证。
如果测试没过或者页面行为和预期不一致，切到诊断技能：
/diagnose让它按「复现 -> 缩小 -> 假设 -> 修复」的顺序处理。常见的情况是状态没正确更新、过滤条件和渲染条件不一致、测试断言写得太宽掩盖了问题。
一个完整的最小对话顺序就是：/setup-matt-pocock-skills->/grill-me->/tdd->/diagnose。记住这个顺序，先问清楚，再写测试，再写实现，最后排查问题。
5. 常见报错排查：401、local proxy failed、reading choices
这一节对照真实报错来排查。我试过几次配置写错的情况，下面这几个是最容易踩的。
401 Unauthorized。这个最常见，基本就是 Key 的问题。检查三件事：Key 有没有复制完整（前后不能有空格）、Key 有没有过期、Key 有没有填到正确的字段里。Claude Code 里是ANTHROPIC_AUTH_TOKEN，Codex 里是auth.json的OPENAI_API_KEY。如果 Key 是对的还报 401，检查 Base URL 是不是写成了https://taotoken.net/api/带了尾部斜杠，有些工具对尾部斜杠敏感，去掉试试。
local proxy failed / connection refused。这个报错说明工具在尝试连本地代理但连不上。检查你的配置里有没有残留的http://localhost:xxxx或者http://127.0.0.1:xxxx地址。Claude Code 的settings.json和 Codex 的config.toml里，Base URL 应该直接指向https://taotoken.net/api，不要经过任何本地转发。另外检查环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向本地端口，有的话清掉。
reading choices / unexpected response format。这个报错通常是模型 ID 写错了，或者 Base URL 指向了一个不兼容的接口。检查ANTHROPIC_MODEL或model字段填的模型 ID 是否在 TaoToken 支持的列表里。Claude 系列用claude-sonnet-4-20250514这种格式，GPT 系列用gpt-5-codex这种格式。模型 ID 写错的话，接口返回的结构对不上，工具解析时就报 reading choices 错误。
OAuth / authentication failed。Codex 有时候会走 OAuth 流程，如果你用的是 API Key 模式，检查auth.json里是不是同时存在 OAuth token 和 API Key，两个同时存在会冲突。把 OAuth 相关的字段删掉，只留OPENAI_API_KEY。Claude Code 同理，如果之前登录过官方账号，settings.json里可能有残留的 OAuth 配置，清掉再试。
技能不生效 / 命令找不到。SKILL.md 放对目录了吗？Claude Code 是.claude/skills/技能名/SKILL.md，Codex 是.codex/skills/技能名/SKILL.md。frontmatter 里的name字段有没有写？name只能用字母数字连字符。改完配置重启工具了吗？这三个都检查一遍。
模型不按技能流程走。有时候技能注册成功了，但模型还是自己发挥。检查 SKILL.md 的description是不是写得太模糊。description 要写「什么时候用」，比如「当用户要求实现新功能时使用」，而不是「这是一个 TDD 技能」。模型靠 description 做路由，写清楚了它才会在合适的时机调用。
6. 把 TaoToken 作为统一通道的长期用法
跑通第一个技能之后，你可能会想把这套流程固定下来。这时候 TaoToken 的价值就体现出来了：一个 Key 管所有模型，Claude Code、Codex、Cline 共用同一个 Base URL，不用每个工具单独配一遍。
长期用的话，建议把配置分成两层。全局配置放~/.claude/settings.json和~/.codex/config.toml，写 TaoToken 的 Base URL 和 Key。项目级配置放.claude/skills/和.codex/skills/，放具体的技能文件。这样换项目的时候，技能跟着项目走，Key 不用重复填。
模型 ID 可以按任务切换。需求澄清和架构设计用 Claude 系列，代码生成和 TDD 用 GPT 系列，在settings.json里改ANTHROPIC_MODEL就行。TaoToken 的模型对话页面可以快速验证某个模型 ID 是否可用，省得在工具里反复试。
如果你要长期跑编码任务或者 Agent 流程，Coding Plan 比按量计费更划算。接入文档里有完整的配置示例，覆盖 Claude Code、Codex、Cline 等主流工具。API Keys 页面管理你的 Key，可以随时生成新的或吊销旧的。
技能文件本身也可以版本化。把.claude/skills/和.codex/skills/提交到 git，团队里每个人拉下来就能用同一套工作流。mattpocock/skills 仓库里的技能可以直接复制进项目，也可以按自己团队的规范改 SKILL.md 的正文部分。改的时候注意别动 frontmatter 的name，那个是调用入口。
最后说一个实际经验：技能不是越多越好。装太多技能会让模型在路由时犹豫，反而降低效率。建议保持 3 到 5 个核心技能，覆盖需求澄清、TDD、诊断这三个环节就够了。其他的按需临时装，用完可以删。
