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和descriptionname决定你调用时敲什么命令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把上下文整理成 PRDzoom-out先看全局再看局部improve-codebase-architecture收敛面条化代码库setup-matt-pocock-skills给当前仓库做基础配置。安装方式分两条路。Claude Code 和部分支持 skills 协议的工具可以用 npx 一键安装npx skillslatest 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 skillslatest add mattpocock/skills/tdd npx skillslatest 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/apiKey 填 TaoToken 的 KeyModel ID 填你要用的模型。Cline 的 MCP 配置里provider 选 OpenAI CompatibleBase 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_TOKENCodex 里是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.mdCodex 是.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、诊断这三个环节就够了。其他的按需临时装用完可以删。