SOURCE
Matt Pocock开源了自己的.claude目录21个Skill,专治Agent 想当然 - 今日头条 摘要
文档概览
- 文中先给出一个反常识背景：这个仓库星标超过 15 万、fork 超过 1.3 万。
- 文章认为，这个数字之所以罕见，是因为仓库内容虽然主要是说明书性质的 Markdown，但真正被开源的是一整套工程纪律。
- 文中同时补充 Matt Pocock 的背景：写过 Total TypeScript，当过 Vercel 的开发者布道师，也在 Stately 做过 XState 核心团队成员，现在专职教开发者做 AI 工程。
- 文章将整套 Skills 总结为 21 个 Skill，覆盖从“有个模糊的想法”到“代码合并进主干”的完整工作流。
关键事实
这套 Skills 试图解决的四类典型问题
- 第一类问题是 Agent 自作主张。
- 具体表现是：用户以为 Agent 理解了需求，但最后产出的东西其实偏题，是最常见的人机失配。
- 第二类问题是 Agent 话太多，而且缺少项目内部的共同语言。
- 具体表现是：项目中的黑话、约定术语、上下文压缩词汇没有沉淀下来，Agent 每次都要重新猜，因此它宁可啰嗦解释，也无法精确表达。
- 第三类问题是代码跑不起来。
- 文中指出，没有测试反馈时，Agent 写代码基本等于“盲人摸象”，因为它缺少可执行的真假判断机制。
- 第四类问题是代码库快速腐化。
- 文章的判断是：Agent 写代码越快，如果没有约束，项目腐化也会越快，几周内就可能变成“谁都不敢动的烂摊子”。
四类对应药方
- 对应 Agent 自作主张，药方是先把需求澄清清楚，而不是直接开写。
- 对应缺少共同语言，药方是显式建立一套 项目共同语言，让团队与 Agent 用同一套术语压缩复杂上下文。
- 对应代码跑不起来，药方是使用红绿重构的测试循环，先有失败测试，再实现，再重构，以保证代码可运行。
- 对应代码库腐化，药方是定期做架构体检和代码审查，防止结构持续恶化。
- 文章的核心观点是：21 个 Skill，本质上就是把这四件事拆解成可重复执行的动作。
项目共同语言的例子
- 文中专门给了一个例子来说明为什么共同语言重要。
- 原本一段复杂描述是：“某节课在某个章节里被落到文件系统上生成实体文件时会出问题”。
- 在建立统一黑话后，这句话被压缩成“物化级联出问题了”。
- 文章借此说明，统一术语后，不仅团队成员沟通成本下降，Agent 也不需要每次重新翻译整段业务语义。
- 这不是单纯缩短句子，而是把上下文打包成一个共享概念，从而提升沟通精度。
重要细节
主线工作流：idea → ship
- 文章把整套系统的核心主线称为
idea → ship。 - 它描述的是：如何把一个模糊想法，逐步推进成最终可合并的代码。
第一步：/grill-with-docs 澄清需求
- 起点是
/grill-with-docs。 - 文中把它形容成“像审问一样”逐条追问用户的决定。
- 它有一个关键约束：能从代码库中查到的事实，它会自己查；只有查不到的内容，才会反过来问用户。
- 这个过程会持续到双方对齐为止，而不是草率地在信息不完整时直接生成实现。
- 因而它承担的职责不是写代码，而是先消除“想当然”。
第二步：必要时走 /prototype 做一次性验证
- 如果某些问题靠讨论无法得出答案，例如某个交互到底顺不顺手，就会从主线分岔到
/prototype。 /prototype的目标不是产出正式实现，而是快速写一段一次性代码把问题跑出来。- 文中强调“验完就扔”，说明这个步骤的价值在于验证，而不是沉淀可维护代码。
- 这也是一个边界条件：只有在聊不出答案、必须通过实际运行验证时，才使用这个 Skill。
第三步：/to-spec 生成规格
- 想清楚之后，下一步是
/to-spec。 - 它负责把前面的对话整理成规格文档。
- 文章将其放在澄清与切分之间，说明其作用是把口头理解转成可引用、可审查的中间产物。
第四步：/to-tickets 切成工单
- 有了规格文档后，再用
/to-tickets把工作拆成一张张工单。 - 文中特别提到，这些工单之间会声明彼此的“卡点关系”。
- 也就是说，它不只是线性拆任务，还会表达依赖、阻塞或前置关系。
- 工单既可以落在本地文件中，也可以接入 Linear 或 GitHub Issues。
- 这说明该工作流同时支持轻量本地使用和接入外部任务系统。
第五步：/implement 执行工单
- 每张工单之后交给
/implement。 - 文章指出，
/implement内部会驱动/tdd。 - 这意味着真正的实现不是“直接生成代码”，而是被纳入测试驱动的纪律流程里。
第六步：/tdd 通过红绿重构循环完成实现
/tdd对应的就是文中前面提到的红绿重构测试循环。- 其目的不是形式化地“写几个测试”，而是让功能在持续验证中从红灯走到绿灯。
- 文章把它视为“代码能跑起来”的关键保障。
第七步：/code-review 收尾审查
- 主线最后会自动跑一次
/code-review。 - 这一步不是单一维度检查，而是双线并行。
- 第一条线检查代码坏味道和经典问题。
- 文中明确给出，这条线内置了 12 条经典问题，例如命名混乱、重复代码等。
- 第二条线检查实现是否跑题，也就是判断产物有没有偏离原始需求与规格。
- 文章强调，两条线彼此独立、互不干扰。
- 这种设计的含义是：代码质量问题与需求对齐问题被分开审查，避免一种视角掩盖另一种风险。
主线之外的三个入口
/triage：把外部粗糙反馈转成可执行工单
- 当需求或 bug 不是从内部规格流程产生，而是从别人扔来的粗糙反馈开始时，入口不是主线最前面的澄清流程，而是
/triage。 /triage的职责是把原始、模糊、质量参差不齐的反馈，处理成 Agent 可以直接承接的工单。- 因而它更像一个输入预处理器，适合对接外部需求、客户反馈或零散 bug 报告。
/diagnosing-bugs：先稳定复现，再修 bug
- 对于莫名其妙的疑难 bug，文章给出的入口是
/diagnosing-bugs。 - 这个 Skill 有一个很强的约束：拒绝瞎猜。
- 它要求必须先找到一个能稳定复现问题的命令，然后才开始修复。
- 这意味着“先复现、后修复”不是建议，而是前置条件。
- 其核心价值在于避免 Agent 在不确定条件下乱改代码。
/wayfinder：高不确定性大型规划，只产出决定不产出代码
/wayfinder是文中认为“最有意思”的入口。- 它专门处理那种“雾很大”的大工程，也就是高不确定性、范围大到一次对话装不下的问题。
- 它的工作方式是：先把已知和未知分成两栏挂到工单系统上，然后一次次解决雾中的问题，逐步看清路径。
- 重要边界是：这个过程中只产出决定，不产出代码。
- 也就是说，它处理的是规划与决策，而非实现。
- 这让它与
/implement、/prototype等执行型 Skill 明确区分开。
/wayfinder 命名调整的插曲
- 文章还保留了一个来自更新日志的小细节。
- 这个 Skill 最初叫
decision-mapping。 - 后来更新日志中明确写到，这个名字“jargon 化又不准确”，因此重新寻找更合适的隐喻，最终改成
wayfinder。 - 文中认为，这种把改名心路过程公开写进更新日志的做法，体现了项目愿意暴露自己的思考和修正，而不是只展示“千锤百炼”的完美成品。
Skill 的分层调用规则
- 文章认为，这套系统真正巧妙的地方，不只是列出 21 个 Skill，而是明确区分了“谁能喊”和“谁自己会来”。
- 第一类是用户唤起。
- 只有用户手动输入类似
/grill-me这样的命令，它们才会运行。 - 这类 Skill 负责统筹全局。
- 第二类是模型唤起。
- Agent 会在判断场景合适时主动调用它们。
- 这类 Skill 负责具体纪律动作，例如
/tdd、/code-review。 - 文中总结出的分层规则很简单：统筹型可以调用纪律型，但两个统筹型之间不能互相调用。
- 文章认为，这条规则解释了为什么用户不需要硬背 21 条命令。
- 大多数情况下，用户只需要记住少数入口，剩下的具体动作由 Agent 根据上下文自己选择。
- 这正是 Skill 分层调用规则 的核心：减少记忆负担，同时保留流程纪律。
关于写 Skill 的一条经验
- 仓库中还包含一份关于如何编写 Skill 的说明。
- 文章特别提炼出其中一条提醒：不要用“不要做什么”来约束模型。
- 文中借用了“别想大象”的心理学式比喻：你越说“不要啰嗦”，其实越把“啰嗦”这个模式摆到模型眼前。
- 更好的写法是直接描述目标行为。
- 文章给出的例子是：与其说“不要啰嗦”，不如说“每句话只讲一件事”。
- 与其反复强调“不要塞进三个从句”，不如直接规定你希望的句法和输出形式。
- 文中认为，这类规则本身不算惊天秘密，但能把失败经验提炼成可复用纪律，正是这套系统最有价值的部分。
安装与初始化
- 文中给出了一个三步式安装说明。
- 第一步，在命令行执行
npx skills@latest add mattpocock/skills。 - 第二步，勾选想要安装的 Skill 和目标 Agent。
- 文中明确提到支持 Claude Code 与 Codex。
- 同时有一个强制提醒：一定要勾上
/setup-matt-pocock-skills。 - 第三步，安装完成后，要在 Agent 里再运行一次
/setup-matt-pocock-skills。 - 这个初始化过程会询问至少三件事：使用哪个 issue tracker、triage 时打什么标签、文档放在哪里。
- 文中强调，只有问完并配置好这三项，其余 20 个 Skill 才算真正对上当前项目。
文章结论
- 文章最后的判断是：一个人的
.claude目录，能被十几万开发者几乎原样搬进自己的项目，并不是偶然。 - 原因在于它把四类 Agent 常见问题想得足够具体，也把相应纪律拆成了可以执行的 Skill。
- 同时，项目愿意把自己走过的弯路、改名过程和失败经验公开留在更新日志中，这种坦诚也是其说服力的重要来源。