应大家的要求，我今天发布了 v1.3 的 skills。/retro 背后有太多期待，不能再拖了。去翻翻你旧的会话记录，看看能做哪些改进吧。文档、视频和发布文章将在周一上线。https://t.co/ItW5zc7fym

— # mattpocock/skills 来源：https://github.com/mattpocock/skills

面向真正工程师的 Skills

skills.sh（https://skills.sh/mattpocock/skills）

我的 agent skills —— 每天都在用来做真正的工程，而不是凭感觉写代码。

开发真正的应用程序是很难的。GSD、BMAD 和 Spec-Kit 这类方法试图通过掌控整个流程来提供帮助。但与此同时，它们会剥夺你的控制权，让流程中的 bug 难以修复。

这些 skills 的设计目标是：小巧、易于改编、可组合。它们适用于任何模型。它们基于数十年的工程经验。动手折腾它们，把它们变成你自己的。祝你玩得开心。

如果你想及时了解这些 skills 的变化，以及我创建的任何新 skills，可以加入我通讯录上的大约 60,000 名开发者：订阅通讯录（https://www.aihero.dev/s/skills-newsletter）

安装（30 秒搞定）

两种途径，两种理念。

**Claude Code 插件（https://code.claude.com/docs/en/plugins）**会把整套 skills 安装为一个受管理的只读包，我发布更新时它会自动更新 —— 所以你是在订阅，而不是 fork。

**skills.sh（https://skills.sh/mattpocock/skills）**会把可编辑的 skill 文件复制到你的项目中，你可以随意改造，把它们变成你自己的。

选一种：两种都装的话，每个 skill 都会出现两次。

1. 获取 skills

Claude Code

claude plugins install mattpocock-skills

或者，在会话中：

/plugin install mattpocock-skills

它已经上架 Claude Code 官方市场，无需额外配置，更新会自动推送。

Codex 及其他 agent

npx skills@latest add mattpocock/skills

选择你想要的 skills，以及要安装到哪些编码 agent 上。

安装器允许你选择要安装哪些 skills，所以请务必把 setup-matt-pocock-skills 也选上。

原生 Codex 插件已在路线图上（参见 .agents/adr/0002-ship-as-a-claude-code-plugin.md）。

喜欢折腾的人

在任何 agent 上使用同一个安装器，包括 Claude Code：

npx skills@latest add mattpocock/skills

它会把 skills 作为普通文件写入你的仓库，文件归你所有，随时可以编辑。没有任何东西会背着你自动更新；当你想要我最新的改动时，运行 npx skills update 即可拉取。

2. 运行 /setup-matt-pocock-skills

在你的 agent 中，每个仓库运行一次。它会：

• 询问你想使用哪个问题跟踪器（GitHub、Linear 或本地文件）
• 询问你在工单分诊时会打哪些标签（/triage 使用标签）
• 询问你想把我们创建的文档保存在哪里

3. 搞定，你可以开始干活了。

这些 Skills 存在的意义

我构建这些 skills，是为了修复我在 Claude Code、Codex 和其他编码 agent 上看到的常见失败模式。

第 1：Agent 没有做我想要的事

“没人能确切知道自己想要什么”

David Thomas & Andrew Hunt，《程序员修炼之道》（https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V）

问题。软件开发中最常见的失败模式是目标不对齐。你以为开发者知道你想要什么。然后你看到他们做出来的东西 —— 才意识到他们完全没理解你。

在 AI 时代也是一样。你和 agent 之间存在沟通鸿沟。解决办法是一场 “拷问式访谈”（grilling session） —— 让 agent 针对你正在构建的东西向你提出详细的问题。

解决方案是使用：

• /grill-me —— 用于非代码场景
• /grill-with-docs —— 与 /grill-me 相同，但额外增加了更多功能（见下文）

这是我最受欢迎的 skills。它们帮助你在开始之前与 agent 对齐，并深入思考你正在做的改动。每当你要做出改动时，都 一定 要使用它们。

第 2：Agent 话太多了

借助通用语言，开发者之间的对话以及代码中的表达都源自同一个领域模型。

Eric Evans，《领域驱动设计》（https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215）

问题：在项目初期，开发者和软件的业务方（领域专家）通常说着不同的“语言“。我在 agent 身上也感受到了同样的张力。Agent 通常是被直接丢进项目里，一边做一边自己摸索项目里的行话。所以它们会用 20 个词来表达本该用 1 个词就能说清的事。

对此的解决方案是一套共享语言。它是一份文档，帮助 agent 解码项目中使用的行话。

示例

这里有一份示例词汇表（https://github.com/mattpocock/course-video-manager/blob/076a5a7a182db0fe1e62971dd7a68bcadf010f1c/CONTEXT.md）（在那个固定的 commit 上仍叫 CONTEXT.md，那时 skills 还没重命名这个约定），来自我的 course-video-manager 仓库。哪一个更好读？

• 改之前：“当课程中某个小节里的课程被 ‘实体化’（即在文件系统中获得一个位置）时，会出现一个问题”
• 改之后：“物化级联（materialization cascade）出了问题”

这种简洁在一次又一次的会话中持续带来回报。它已经内置于 /grill-with-docs。它是一场拷问式访谈，但还会帮你和 AI 共同建立一套共享语言，并将难以解释的决策记录到 ADR 中。

很难解释这件事有多强大。它可能是这个仓库里最酷的一项技术。试一试就知道了。

共享语言的好处远不止减少冗余：

• 变量、函数和文件命名保持一致，使用统一的共享语言
• 因此，代码库对 agent 来说更容易导航
• agent 在思考上花费的 token 也更少，因为它能使用一种更简洁的语言

第 3：代码跑不起来

“始终采取小而深思熟虑的步骤。反馈的速度就是你的限速。永远不要承担过大的任务。”

David Thomas & Andrew Hunt，《程序员修炼之道》（https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V）

问题：假设你和 agent 已经就要构建什么达成了共识。当 agent 仍然 产出垃圾时该怎么办？是时候检视你的反馈循环了。如果没有关于它产出的代码实际运行情况的反馈，agent 就是在盲飞。

解决方案：你需要那套常规的反馈机制：静态类型、浏览器访问和自动化测试。对于自动化测试，红-绿-重构（red-green-refactor）循环至关重要。也就是 agent 先写一个失败的测试，然后让测试通过。这有助于给 agent 提供一致的反馈水平，从而产出好得多的代码。

我构建了一个 /tdd skill，你可以把它插入任何项目。它鼓励红-绿-重构，并为 agent 提供大量关于什么是好测试、什么是坏测试的指导。

对于调试，我还构建了 /diagnosing-bugs skill，它把最佳调试实践包装成一个纪律严格的循环，逐阶段进行把关。

第 4：我们建出了一团泥巴

“每天 都要投入系统设计。”

Kent Beck，《解析极限编程》（https://www.amazon.co.uk/Extreme-Programming-Explained-Embrace-Change/dp/0321278658）

“最好的模块是深的。它们允许通过简单的接口访问大量的功能。”

John Ousterhout，《软件设计的哲学》（https://www.amazon.co.uk/Philosophy-Software-Design-2nd/dp/173210221X）

问题：大多数用 agent 构建的应用复杂且难以修改。因为 agent 能极大地加速编码，它们也同时加速了软件的熵增。代码库以空前的速度变得越来越复杂。

对此的解决方案是一种全新的 AI 驱动开发方式：关注代码的设计。它内置于这些 skills 的每一层：

• /to-spec 会在创建规格说明之前，先就你会触及哪些模块向你提问

而最关键的是，/improve-codebase-architecture 会扫描代码库中的“深化“机会，并把候选方案交给你。我建议每隔几天在你的代码库上运行一次它。它是一次调研，不是一次拯救：在一个真正老旧的代码库上，它会找到真正的候选机会，但它不会替你理清这团乱麻。

总结

软件工程的基本功比以往任何时候都更重要。这些 skills 是我尽最大努力将这些基本功浓缩为可重复的实践，帮助你发布职业生涯中最好的应用。祝你玩得开心。

参考

这些 skills 按一条轴线划分：谁可以调用它们。

**用户调用（User-invoked）**的 skill 只有在你输入时才能触发（例如 /grill-me）；它们的职责是编排。

**模型调用（Model-invoked）**的 skill 可以由你调用，也可以 在任务匹配时由 agent 自动调用；它们承载可复用的工程纪律。

用户调用的 skill 可以调用模型调用的 skill，但绝不会调用另一个用户调用的 skill。

工程类 Skills

我每天写代码时使用的技能。

用户调用

• ask-matt：询问哪个 skill 或流程适合你的情况。它是本仓库中用户调用 skills 的路由器。
• grill-with-docs：拷问式访谈，同时还会构建你的项目领域模型，优化术语，并同步更新 GLOSSARY.md 和 ADR。
• triage：让问题在分诊角色的状态机中流转。
• improve-codebase-architecture：扫描代码库中的深化机会，以可视化的 HTML 报告呈现，然后对你选择的候选机会进行拷问式访谈。
• setup-matt-pocock-skills：为本仓库配置工程类 skills（问题跟踪器、分诊标签、领域文档布局）。使用其他工程 skills 之前，每个仓库运行一次。
• to-spec：把当前对话转化为一份规格说明，并发布到问题跟踪器。不需要访谈，只对你已经讨论过的内容进行综合。
• to-tickets：把任何计划、规格说明或对话拆解为一组“曳光弹“（tracer-bullet）工单，每个工单声明其阻塞关系，以文本形式写入本地文件，或作为真实的跟踪器上的原生阻塞链接。
• implement：构建规格说明或工单所描述的工作，在事先约定的接缝处驱动 /tdd，并在提交前以 /code-review 收尾。
• implement-spec：在一个集成分支上实现整份规格说明。把工单当作任务图来执行，针对“就绪前沿“并行运行实现者子 agent 以实现最大并发，然后以 /code-review 收尾。
• wayfinder：规划一大块超出单个 agent 会话容量的工作，在问题跟踪器上以决策工单的共享地图形式呈现，然后逐个解决，直到通往目的地的路线清晰可见。
• retro：在一次会话之后，对编码 agent 的环境（导航、自动化检查、编码规范、引导文件、工具链）提出改进建议，按严重程度从高到低排列。

模型调用

• prototype：构建一个用完即弃的原型来回答一个设计问题 —— 对于状态/逻辑问题，可以是一个可分享的单个 HTML 文件；也可以是几个截然不同的 UI 变体，通过同一路由切换。
• diagnosing-bugs：针对疑难 bug 和性能回归的严谨诊断循环：先建立一个能在这个 bug 上变红的反馈循环 → 最小化 → 假设 → 插桩 → 修复 → 回归测试。
• research：针对高可信的原始资料调研一个问题，并将结论以带引用的 Markdown 文件记录在仓库中，以后台 agent 方式运行。
• tdd：采用红-绿-重构循环的测试驱动开发。按垂直切片逐个构建功能或修复 bug。
• domain-modeling：主动构建并打磨项目的领域模型：对照词汇表挑战术语，用边界场景进行压力测试，并同步更新 GLOSSARY.md 和 ADR。
• codebase-design：设计深模块时共享的纪律与词汇：在简洁的接口背后实现大量行为，放置在干净的接缝上，并能通过该接口进行测试。
• code-review：对某个固定基点以来的 diff 进行双轴评审：规范（Standards）（是否符合仓库的编码规范，以及 Fowler 的代码坏味道基线？）和规格（Spec）（是否忠实地实现了原始问题/规格？），以后台并行子 agent 运行，互不干扰。
• pr：PR 描述应有的形态：以最小的视觉呈现作为摘要让改动一目了然，附上改动生效的前后证据，并给出合并风险判断（单向门还是双向门，加上影响范围）。
• wizard：生成一个交互式 bash 向导，引导人类完成只有他们能执行的步骤：预置基础设施、配置凭据或 CI 密钥、操作一个不熟悉的第三方仪表盘，或运行一次性迁移或切换。

生产力类

通用的工作流工具，不局限于代码。

用户调用

• [grill-me](./skills/productivity/grill-me/SKILL.md）：对某个计划或设计穷追不舍地提问，直到设计树的每一个分支都被理清。
• [handoff](./skills/productivity/handoff/SKILL.md）：把当前对话压缩成一份交接文档，让另一个 agent 能够继续这项工作。
• [teach](./skills/productivity/teach/SKILL.md）：在多个会话中向用户教授一项新技能或概念，以当前目录作为有状态的教学工作区。
• [to-questionnaire](./skills/productivity/to-questionnaire/SKILL.md）：把你独自无法回答的决策，转化为一份 Markdown 问卷，交给唯一能回答的那个人填写 —— 可以异步填写，也可以一起开会填写。它拷问的是“发送“本身（问卷发给谁、你需要得到什么答案），而不是问卷的主题。
• [wait-what](./skills/productivity/wait-what/SKILL.md）：当某条消息没被理解时，立刻触发它。Agent 会用你所缺失的上下文重新表述，用大白话，用你 GLOSSARY.md 中的词汇。

模型调用

• [grilling](./skills/productivity/grilling/SKILL.md）：对计划、决策或想法穷追不舍地向用户提问，直到设计树的每一个分支都被理清。这是 grill-me、grill-with-docs、triage、wayfinder 和 improve-codebase-architecture 背后可复用的访谈原语。
• [writing-for-agents](./skills/productivity/writing-for-agents/SKILL.md）：为 agent 撰写文档：skills、AGENTS.md/CLAUDE.md，以及任何 agent 能通过指针触达的文档。