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

真正工程师的技能

skills.sh (https://skills.sh/mattpocock/skills)

我每天用来做真正工程——而非氛围编码——的代理技能。

开发真正的应用程序是困难的。像 GSD、BMAD 和 Spec-Kit 这类方法，试图通过掌控流程来提供帮助。但与此同时，它们夺走了你的控制权，并使过程中的 bug 难以解决。

这些技能的设计理念是小巧、易于适配且可组合。它们适用于任何模型。它们基于数十年的工程经验积累。

你可以随意修改、客制化它们。玩得开心。

如果你想跟进这些技能的更新，以及我创建的任何新技能，可以加入我 newsletter 上约 60,000 名开发者：订阅 newsletter (https://www.aihero.dev/s/skills-newsletter)

快速入门（30 秒设置）

1. 运行 skills.sh 安装器：bash npx skills@latest add mattpocock/skills
2. 挑选你想要的技能，以及你想在哪些编码代理上安装它们。确保你选择了 /setup-matt-pocock-skills。
3. 在你的代理中运行 /setup-matt-pocock-skills。它会：
   • 询问你想使用哪个问题追踪器（GitHub、Linear 或本地文件）
   • 询问你在分类问题时会打上什么标签（/triage 使用标签）
   • 询问你想把我们创建的任何文档保存在哪里
4. 搞定——一切就绪。

这些技能为什么存在

我创建这些技能是为了解决我在使用 Claude Code、Codex 和其他编码代理时看到的常见失败模式。

#1：代理没按我的想法做

“没人真正确切地知道自己想要什么”

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

问题所在。软件开发中最常见的失败模式就是对齐偏差。你以为开发者知道你想要什么，然后当你看到他们构建的东西时——才意识到它根本没理解你。这在 AI 时代也是一样。你和代理之间存在沟通鸿沟。

解决办法是进行一场盘问环节——让代理就你正在构建的内容提出详细问题。

修复手段是使用：

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

这是我最受欢迎的技能。它们能在你开始之前帮助你与代理对齐，并促使你深入思考你即将做出的变更。每次你想要做出变更时都应该使用它们。

#2：代理实在太啰嗦了

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

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

问题所在：项目开始时，开发者和他们为之构建软件的人（领域专家）通常说着不同的语言。我在与代理协作时也感受到了同样的张力。代理通常被直接扔进一个项目，被要求边做边摸索术语。因此它们本可以用一个词表达清楚的地方却用了 20 个词。

修复手段是建立一种共享语言。这是一份文档，帮助代理解码项目中使用的行话。

示例： 这里有一个来自我的 course-video-manager 仓库的 CONTEXT.md (https://github.com/mattpocock/course-video-manager/blob/076a5a7a182db0fe1e62971dd7a68bcadf010f1c/CONTEXT.md) 示例。哪一个更容易理解？

• 改造前：“当课程中某个章节里的一个课被‘实体化’（即在文件系统中给定一个位置）时，会出现一个问题”
• 改造后：“实体化级联存在问题”

这种简洁性会在一次次会话中持续带来回报。

这一点已经内置在 /grill-with-docs 中。它是一次盘问环节，但能帮助你与 AI 建立共享语言，并将难以解释的决策记录在 ADR（架构决策记录）中。很难解释这有多强大，它很可能是本仓库中最酷炫的技巧。试试看，眼见为实。

共享语言除了降低啰嗦程度外，还有许多其他好处：

• 变量、函数和文件的命名更一致，都使用共享语言
• 从而，代码库对代理来说更易于导航
• 代理在思考上消耗的 token 也更少，因为它可以使用更简洁的语言

#3：代码不起作用

“永远采取小步快跑、深思熟虑的步骤。反馈的频率就是你的速度极限。永远不要接手一个过大的任务。”

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

问题所在：假设你和代理在要构建什么上已经对齐。但如果代理仍然产出糟糕的代码，该怎么办？这时你该审视你的反馈回路了。如果没有关于它生成的代码实际如何运行的反馈，代理就相当于在盲目飞行。

修复手段：你需要常规的反馈回路组合：静态类型、浏览器访问和自动化测试。对于自动化测试，红-绿-重构循环至关重要。这是指代理先编写一个会失败的测试，然后再修复测试。这有助于给代理提供持续稳定的反馈，从而产出好得多的代码。

我为任何项目构建了一个 /tdd 技能，可以随时嵌入。它鼓励红-绿-重构，并就何为好的测试、何为坏的测试为代理提供了大量指导。

对于调试，我还构建了一个 /diagnose 技能，它将最佳调试实践封装进了一个简单的循环中。

#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)

问题所在：大多数用代理构建的应用都复杂且难以变更。因为代理能极大地加快编码速度，它们也加速了软件的熵增。代码库以空前的速度变得复杂。

修复手段是采用一种全新的 AI 驱动开发方法：关心代码的设计。这已融入到这些技能的每一个层面：

• /to-prd 会在创建 PRD（产品需求文档）前，询问你将触及哪些模块
• /zoom-out 会告诉代理要在整个系统上下文中解释代码

至关重要的是，/improve-codebase-architecture 帮助你拯救一个已经变成大泥球的代码库。我建议每隔几天就在你的代码库上运行一次。

总结

软件工程的基本功比以往任何时候都重要。这些技能是我将这些基本功浓缩成可重复实践的最佳努力，旨在帮助你交付职业生涯中最好的应用。

享受吧。

参考

工程技能

我日常用于代码工作的技能。

• diagnose — 用于棘手 bug 和性能回退的严谨诊断循环：复现 → 最小化 → 假设 → 插桩 → 修复 → 回归测试。
• grill-with-docs — 盘问环节，挑战你的计划与现有领域模型的契合度，打磨术语，并内联更新 CONTEXT.md 和 ADR。
• triage — 通过一种分类角色状态机对问题进行分诊。
• improve-codebase-architecture — 在代码库中寻找深化设计的机会，依据 CONTEXT.md 中的领域语言和 docs/adr/ 中的决策。
• setup-matt-pocock-skills — 搭建每个仓库的配置（问题追踪器、分诊标签词汇表、领域文档布局），供其他工程技能使用。在使用 to-issues、to-prd、triage、diagnose、tdd、improve-codebase-architecture 或 zoom-out 之前，每个仓库运行一次。
• tdd — 采用红-绿-重构循环的测试驱动开发。每次构建功能或修复 bug 都按一个垂直切片进行。
• to-issues — 将任何计划、规格说明或 PRD 拆分为可以独立处理的 GitHub issues，采用垂直切片。
• to-prd — 将当前对话上下文转化为 PRD 并作为 GitHub issue 提交。没有访谈——只综合你已经讨论过的内容。
• zoom-out — 告诉代理放远视野，为不熟悉的代码段提供更广泛的上下文或更高层次的视角。
• prototype — 构建一个用完即弃的原型来充实设计——可以是一个可运行的终端应用，用于解决状态/业务逻辑问题；或者是几个截然不同的、可从同一路由切换的 UI 变体。

生产力

通用工作流工具，非代码专用。

• caveman — 超压缩通信模式。通过去除冗余信息，在保持完全技术准确性的同时，削减约 75% 的 token 消耗。
• grill-me — 就一个计划或设计接受无休止的质询，直到决策树的每个分支都被解决。
• handoff — 将当前对话压缩成交接文档，以便另一个代理可以继续工作。
• write-a-skill — 以恰当的结构、渐进式披露和捆绑资源创建新技能。

杂项

我保留但不常使用的工具。

• git-guardrails-claude-code — 设置 Claude Code 钩子，在执行危险 git 命令（push、reset –hard、clean 等）前加以阻止。
• migrate-to-shoehorn — 将测试文件从 as 类型断言迁移到 @total-typescript/shoehorn。
• scaffold-exercises — 创建带有章节、问题、解答和说明的练习目录结构。
• setup-pre-commit — 使用 lint-staged、Prettier、类型检查和测试设置 Husky 的 pre-commit 钩子。