1. 为什么你的 Claude Code 用着用着就乱了先说一个我观察到的现象很多人第一次用 Claude Code 时惊为天人觉得 AI 终于能干活了用了一个月之后项目里堆满了「看起来能跑但没人敢改」的代码每次对话都要重新解释一遍项目背景改一个 bug 顺手引入两个新 bug。问题不在模型在于你把 Claude Code 当成了一个「更聪明的补全工具」而不是一个需要工程纪律约束的协作者。mattpocock/skills 这个仓库就是冲这件事来的。它是 Matt Pocock 维护的一套 Claude Code 技能集MIT 协议开源按 engineering/ 和 productivity/ 两个桶组织插件清单里正式推广的技能一共 22 个。它的口号是「Skills For Real Engineers」——不是让 AI 写更多代码而是让 AI 写对的代码。这套技能解决四个具体的失败模式AI 没按预期做需求理解偏差、AI 太啰嗦每次重复解释背景、代码不工作调试靠猜、架构成 mud ball越写越乱。对应的技能方向分别是 /grill-me 系列、CONTEXT.md、/tdd 与 /diagnosing-bugs、/to-spec 与 /domain-modeling。这篇文章不讲「这 22 个技能分别是什么」这种清单式介绍而是带你把这套东西真正落到自己的项目里搭出可复制的技能目录骨架、写出能用的 CONTEXT.md、配好 settings.json最后逐条验证技能是否生效。适合已经在用 Claude Code、但觉得自己还在「聊天式编程」里打转的开发者。2. 前置准备把技能库接进你的工作流2.1 两种安装方式怎么选mattpocock/skills 提供两种安装路径选哪种取决于你要不要改技能源码。可编辑安装适合想按需魔改技能提示词的团队命令是把技能复制进项目npx skillslatest add mattpocock/skills只读托管安装适合希望自动更新的个人开发者走 Claude Code 插件市场/plugin marketplace add mattpocock/skills /plugin install mattpocock-skillsmattpocock我自己的做法是主力项目用可编辑安装因为团队对「追问粒度」有自定义要求个人小项目用托管安装省心。2.2 安装后第一件事跑 setup装完别急着用技能先运行初始化命令/setup-matt-pocock-skills它会引导你配置三样东西问题追踪器GitHub Issues、Linear 或本地文件、triage 标签体系、文档保存位置。这一步很多人跳过结果后面 /to-spec 生成的 spec 文档不知道往哪放/diagnosing-bugs 也接不上你的 issue 系统。2.3 关于模型接入的一点说明Claude Code 本身需要模型服务支撑。如果你在找稳定的接入方式TaoToken 提供兼容 Anthropic 协议的 API 端点配置方式是在环境变量里指定 base URLexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的keyAPI Key 在控制台的 API Keys 页面生成https://taotoken.net/console/api-keys 。这一步和技能库本身是解耦的技能是提示词层的工程化模型接入是基础设施层两者互不影响。想先验证模型连通性的话可以直接在模型对话页面发一条测试消息https://taotoken.net/model-chat 。3. 可复制配置技能目录骨架 CONTEXT.md settings.json3.1 技能目录骨架可编辑安装后你的项目里会出现类似这样的结构。我建议在此基础上做一层整理把「团队自定义」和「上游技能」分开your-project/ ├── .claude/ │ ├── skills/ # 技能本体 │ │ ├── engineering/ │ │ │ ├── grill-me/ │ │ │ ├── grill-with-docs/ │ │ │ ├── tdd/ │ │ │ ├── diagnosing-bugs/ │ │ │ ├── to-spec/ │ │ │ ├── domain-modeling/ │ │ │ └── improve-codebase-architecture/ │ │ └── productivity/ │ ├── settings.json # Claude Code 配置 │ └── commands/ # 自定义斜杠命令 ├── CONTEXT.md # 共享语言文件重点 ├── docs/ │ └── specs/ # /to-spec 输出目录 └── src/关键点CONTEXT.md 放在仓库根目录不要塞进 .claude/ 里。因为它的定位是「项目共享语言」应该和 README 同级让任何进入项目的人包括 AI第一眼就能看到。3.2 CONTEXT.md 模板这是整套工作流里最值得花时间打磨的文件。它的作用是沉淀领域术语、架构决策和约定让 Claude Code 在后续对话中自动复用而不是每次从头解释。我实测下来一个有效的 CONTEXT.md 应该包含四块# CONTEXT ## 领域术语 - **Order订单**用户提交的购买意图状态机为 draft → paid → shipped → closed。 - **Settlement结算单**一个订单对应零或一个结算单由支付回调触发创建。 - **SKU**最小库存单位与商品是多对一关系。 ## 架构决策 - 所有跨模块调用必须经过 application 层禁止 domain 层直接依赖 infrastructure。 - 领域事件通过内存总线同步派发暂不引入消息队列ADR-007。 - 金额一律用整数分表示禁止浮点数。 ## 编码约定 - 新增领域概念必须先写测试再写实现见 /tdd。 - 错误处理统一用 Result 类型禁止抛裸异常穿透边界。 - 命名遵循 Ubiquitous Language术语以本文件为准。 ## 已知技术债 - 用户模块的权限校验散落在 controller 层待迁移到 domain service。写 CONTEXT.md 有个坑不要写成 README 的复制品。README 面向人类读者讲「怎么跑起来」CONTEXT.md 面向 AI 协作者讲「这个项目里每个词是什么意思、哪些事不能做」。术语定义越精确AI 的追问质量越高。3.3 settings.json 配置片段Claude Code 的 settings.json 用来声明权限、环境变量和默认行为。一个和技能库配合的配置大概长这样{ permissions: { allow: [ Read, Glob, Grep, Bash(npm test:*), Bash(npm run lint:*) ], deny: [ Bash(rm -rf:*), Bash(git push --force:*) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api }, includeCoAuthoredBy: false }这里有两个设计考虑。第一allow 里放的是「读操作 测试 lint」这些是 /tdd 和 /diagnosing-bugs 高频调用的命令预授权能减少打断。第二deny 里放破坏性命令防止 AI 在排错时「手滑」。如果你打算长期跑编码任务或 Agent 流程可以了解一下 Coding Plan它针对高频调用场景做了额度优化https://taotoken.net/coding-plan 。4. 逐条验证确认技能真的生效了配置写完不代表技能生效。下面是我验证每个技能是否正常工作的操作步骤按工作流顺序排列。4.1 验证需求对齐技能先测 /grill-me。它的设计目标是让 AI 主动追问需求边界而不是直接动手写代码。/grill-me 我要加一个用户邀请功能预期结果AI 不应该立刻给你代码而应该反问。比如「邀请链接有效期多久」「是否需要邮箱验证」「被邀请用户的角色如何限制」「邀请失败如何重试」。如果它直接开始写实现说明技能没加载成功检查 .claude/skills/engineering/grill-me/ 目录是否存在。/grill-with-docs 是加强版会结合 CONTEXT.md 里的术语追问。验证方法是先确认 CONTEXT.md 里有相关术语定义再运行/grill-with-docs 重构订单结算流程如果 AI 的追问里出现了你 CONTEXT.md 中定义的「Settlement」「SKU」等词说明共享语言文件被正确读取了。4.2 验证 CONTEXT.md 是否被复用这个验证不需要特定命令。开一个新对话问一个和领域相关的问题订单和结算单是什么关系如果 AI 回答「一个订单对应零或一个结算单由支付回调触发创建」说明它读到了 CONTEXT.md。如果它开始泛泛而谈电商系统的一般设计说明文件没被加载——检查文件名是否严格是 CONTEXT.md位置是否在仓库根目录。4.3 验证 TDD 技能/tdd 的核心约束是「先写测试再写实现」。验证命令/tdd 实现一个校验邮箱格式的工具函数预期行为AI 应该先输出测试文件等你确认后再写实现。如果它一次性把测试和实现都吐出来说明约束没生效。这时候检查技能目录里的提示词文件看是不是被你的自定义配置覆盖了。一个更严格的验证方式是故意给一个边界模糊的需求/tdd 实现一个解析用户输入的日期函数好的 /tdd 会先追问「支持哪些格式」「时区如何处理」「非法输入返回什么」然后才写测试。这体现了它和 /grill-me 的组合能力。4.4 验证架构治理技能/to-spec 把对话沉淀成 spec 文档。验证方式/to-spec运行后检查 docs/specs/ 目录下是否生成了新的 markdown 文件内容是否包含你刚才讨论的需求要点。如果目录是空的回到 2.2 节重新跑 /setup-matt-pocock-skills 配置文档保存位置。/improve-codebase-architecture 会扫描代码库找改进点。验证命令/improve-codebase-architecture预期结果它应该输出一份「深度化机会」清单比如「这个模块的接口太浅建议合并」「这里存在循环依赖」。如果它只是泛泛地说「代码质量不错」可能是扫描范围没配对。5. 本篇常见错排查5.1 技能命令不识别输入 /grill-me 提示「未知命令」。原因通常是技能没装到 Claude Code 能识别的路径。检查两点一是 .claude/skills/ 目录结构是否正确二是插件是否在 /plugin 列表里显示为已安装。可编辑安装和托管安装的路径不一样别混用。5.2 CONTEXT.md 写了但 AI 不读最常见的原因是文件位置错了。它必须在仓库根目录和 .git 同级。放在 docs/ 或 .claude/ 里都不会被自动加载。另一个原因是文件太大——CONTEXT.md 应该控制在几百行以内只放「术语 决策 约定」不要把整个架构文档搬进去。5.3 /tdd 不先写测试先确认技能版本。上游仓库更新频繁旧版本的 /tdd 约束可能较弱。用可编辑安装的话检查技能提示词文件里是否有「必须先输出测试」的明确指令。另外如果你的 settings.json 里配置了自动执行权限AI 可能会跳过确认直接写实现把相关 Bash 权限改成需要确认。5.4 模型请求报错如果技能加载正常但对话时报连接错误问题在模型接入层不在技能库。检查 ANTHROPIC_BASE_URL 是否配置正确API Key 是否有效。接入文档在这里https://taotoken.net/doc 。想快速排除是模型问题还是技能问题可以先去模型对话页面单独发一条消息测试https://taotoken.net/model-chat 。5.5 技能之间互相干扰22 个技能不是让你全开的。如果你发现 /grill-me 的追问被 /tdd 的测试生成覆盖了说明你在同一个对话里触发了多个技能。正确做法是按工作流分阶段先 /grill-me 对齐需求再 /to-spec 沉淀文档最后 /tdd 写实现。每个阶段开新对话用 CONTEXT.md 和 spec 文档做上下文传递。6. 把技能库变成你自己的mattpocock/skills 的价值不在于那 22 个技能本身而在于它示范了一种思路把零散的提示词沉淀成有目录结构、有共享语言、有验证方法的工程资产。你可以从最小可用集开始CONTEXT.md /grill-me /tdd 三个东西就能覆盖「需求对齐 → 测试驱动」这条主线。跑顺了再逐步加 /to-spec、/domain-modeling、/improve-codebase-architecture 做架构治理。如果你还在选模型接入方案可以先在模型对话页面验证连通性再决定要不要上 Coding Plan 跑长期任务。技能库是提示词层的工程化模型接入是基础设施层两层都稳了AI 编程工作流才真正可维护。最后一句实操建议CONTEXT.md 不要一次写完让它跟着项目长。每次你发现「这句话我解释第二遍了」就把它写进 CONTEXT.md。三个月后回头看这个文件就是你这个项目最值钱的文档。