面向真实工程师的技能¶

我每天用来做真实工程开发的代理技能——不是氛围编程。

开发真实应用很难。GSD、BMAD 和 Spec-Kit 等方法试图通过掌控流程来提供帮助。但与此同时，它们会夺走你的控制权，并让流程中的缺陷难以解决。

这些技能被设计得小巧、易于适配且可组合。它们适用于任何模型。它们基于数十年的工程经验。随意改造它们。让它们成为你自己的。玩得开心。

如果你想跟踪这些技能的变更，以及我创建的任何新技能，可以加入我的邮件列表，与约 60,000 名其他开发者一起：

安装（30 秒设置）¶

两种进入方式，两种理念。Claude Code 插件 将整套技能作为受管理的只读捆绑包安装，当 Anthropic 的市场收录我的发布时会自动更新，因此你是在订阅而不是分叉。skills.sh 会将可编辑的技能文件复制到你的项目中，这样你就可以改造它们并让它们成为你自己的。二选一：同时安装两者会让每个技能都出现两次。

1. 获取技能¶

Claude Code

claude plugins install mattpocock-skills

或者，在会话内部：

/plugin install mattpocock-skills

它在 Claude Code 的官方市场中，因此无需先添加任何内容。如果提示找不到插件，请运行 claude plugins marketplace update 并重试。当 Anthropic 的市场将其固定版本移动到新发布时，更新才会到达你，这可能会比该仓库滞后几天或几周。

卡在旧版本上？ claude plugin list 会显示你当前拥有的版本，CHANGELOG.md 会显示最新发布。若要改为直接跟踪此仓库，请切换到它自己的市场，并在 /plugin → Marketplaces 下为其开启自动更新（对于 Anthropic 之外的市场，默认关闭）：

claude plugin uninstall mattpocock-skills@claude-plugins-official
claude plugin marketplace add mattpocock/skills
claude plugin install mattpocock-skills@mattpocock

Codex 和其他代理

npx skills@latest add mattpocock/skills

选择你想要的技能，以及要将它们安装到哪些编码代理上。安装程序允许你选择要获取哪些技能，因此请确保 setup-matt-pocock-skills 是其中之一。

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

给折腾者

使用同一个安装程序，适用于任何代理，包括 Claude Code：

npx skills@latest add mattpocock/skills

它会将技能作为你拥有并可编辑的普通文件写入你的仓库。不会在背后自动更新；当你想要我的最新更改时，用 npx skills update 拉取。

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

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

询问你想使用哪个问题跟踪器（GitHub、GitLab、本地文件，或你描述的其他任何内容）
询问你在分诊工单时会给它们打什么标签（/triage 会使用标签）
询问你想将我们创建的文档保存到哪里

3. 搞定 - 准备就绪。¶

这些技能为何存在¶

我创建这些技能，是为了修复我在 Claude Code、Codex 和其他编码代理中看到的常见失败模式。

#1：代理没有按我的要求做¶

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

David Thomas 和 Andrew Hunt，《The Pragmatic Programmer》(https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)

问题。软件开发中最常见的失败模式是错位。你以为开发者知道你想要什么。然后你看到他们构建的东西——你意识到它根本没有理解你。

在 AI 时代也是如此。你和代理之间存在沟通鸿沟。解决这个问题的方法是进行一次追问会话——让代理就你要构建的内容向你提出详细问题。

修复方法是使用：

/grill-me - 用于非代码场景
/grill-with-docs - 与 /grill-me 相同，但增加了更多实用内容（见下文）

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

#2：代理太啰嗦了¶

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

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

问题：在项目开始时，开发者和他们为其构建软件的人（领域专家）通常说着不同的语言。

我在智能体身上也感受到同样的张力。智能体通常被直接丢进项目，并被要求边做边弄懂行话。因此，它们会用 20 个词来表达本可以用 1 个词说清的意思。

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

示例

这是一个示例术语表（在那个固定提交中仍命名为 CONTEXT.md，早于技能重命名该约定），来自我的 course-video-manager 仓库。哪一个更容易阅读？

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

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

这已内置于 /grill-with-docs。这是一次拷问式会话，但它能帮助你与 AI 建立共享语言，并在 ADR 中记录难以解释的决策。

很难解释它有多强大。它可能是这个仓库里最酷的一项技术。试试，然后看看。

[!TIP] 共享语言除了减少冗长之外，还有许多其他好处：

变量、函数和文件命名保持一致，使用共享语言

因此，代码库对智能体来说更容易导航

智能体也在思考上消耗更少的 Token，因为它可以使用更简洁的语言

#3：代码无法运行¶

“始终采取小而审慎的步骤。反馈速率就是你的速度上限。永远不要接手太大的任务。”

大卫·托马斯 & 安德鲁·亨特，《程序员修炼之道》

问题：假设你和智能体已经就构建什么达成一致。当智能体_仍然_产出垃圾时，该怎么办？

是时候审视你的反馈循环了。如果没有关于它生成的代码实际如何运行的反馈，智能体就会盲目摸索。

解决方案：你需要一套常规的反馈循环：静态类型、浏览器访问和自动化测试。

对于自动化测试，红-绿-重构循环至关重要。智能体先写一个失败的测试，然后修复测试。这有助于给智能体提供一致级别的反馈，从而产生好得多的代码。

我构建了一个可以嵌入任何项目的 /tdd 技能。它鼓励红-绿-重构，并给智能体大量关于什么构成好测试和坏测试的指导。

对于调试，我还构建了一个 /diagnosing-bugs 技能，它将最佳调试实践封装成一个有纪律的循环，并逐阶段把关。

#4：我们造出了一个泥球¶

“_每天_都投资于系统设计。”

肯特·贝克，《极限编程详解》

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

约翰·奥斯特霍特，《软件设计哲学》

问题：大多数用智能体构建的应用复杂且难以修改。因为智能体能极大加快编码速度，它们也加速了软件熵。代码库以前所未有的速度变得更复杂。

对此的解决方案是一种针对 AI 驱动开发的激进新方法：关心代码设计。

这内置于这些技能的每一层：

/to-spec 在创建规范之前，会询问你将触及哪些模块

而关键在于，/improve-codebase-architecture 会调查代码库中的深化机会，并把候选项交给你。我建议每隔几天就在你的代码库上运行一次。它是调查，不是救援：在一个真正陈旧的代码库上，它会找到真实的候选项，但不会替你解开泥球。

摘要¶

软件工程基础比以往任何时候都更重要。这些技能是我尽力将这些基础浓缩为可重复的实践，以帮助你交付职业生涯中最好的应用。祝使用愉快。

参考¶

它们沿一个维度划分：谁能调用它们。用户调用技能只有在你输入时才能被调用（例如 /grill-me）；它们的工作是编排。模型调用技能可以由你调用，_或者_当任务匹配时由智能体自动调用；它们承载可复用的纪律。用户调用技能可以调用模型调用技能，但绝不能调用另一个用户调用技能。

工程¶

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

用户调用

ask-matt：询问哪种技能或流程适合你的情况。它是本仓库中用户调用技能的路由器。
grill-with-docs：一次拷问式会话，同时构建你项目的领域模型，打磨术语，并内联更新 GLOSSARY.md 和 ADR。
triage：让问题通过分诊角色状态机流转。
improve-codebase-architecture：扫描代码库中的深化机会，将它们呈现为可视化 HTML 报告，然后对你选中的那一项进行拷问。
setup-matt-pocock-skills：为此仓库配置工程技能（问题跟踪器、分诊标签、领域文档布局）。在使用其他工程技能之前，每个仓库运行一次。
to-spec：将当前对话转化为规范并发布到问题跟踪器。不访谈，只综合你们已经讨论过的内容。
to-tickets：将任何计划、规范或对话拆分为一组曳光弹式工单，每个工单都声明其阻塞边，可以写成本地文件中的文本，或作为真实跟踪器上的原生阻塞链接。
implement：构建由规范或一组工单描述的工作，在预先约定的接缝处驱动 /tdd，并在提交前以 /code-review 收尾。
implement-spec：在一个集成分支上实现整个规范。将工单作为任务图处理，在就绪前沿上运行实现子智能体以获得最大并发，然后以 /code-review 收尾。
wayfinder：将一大块工作（超过一次智能体会话所能承载的范围）规划为问题跟踪器上决策工单的共享地图，并逐个解决，直到通往目标的路径清晰为止。
retro：在一次会话后，建议改进编码智能体的环境（导航、自动化检查、编码标准、引导文件、工具），最严重的优先。

模型调用

prototype: 构建一次性原型以回答设计问题：对于状态/逻辑问题，可以是单个可共享的 HTML 文件；或者从同一路由切换的多个截然不同的 UI 变体。
diagnosing-bugs: 针对疑难 bug 和性能回归的严格诊断循环：构建一个反馈循环，使其在该 bug 上变红 → 最小化 → 提出假设 → 插桩 → 修复 → 回归测试。
research: 针对高可信度的一手来源调查问题，并将发现记录为仓库中一个带引用的 Markdown 文件，作为后台代理运行。
tdd: 采用红-绿-重构循环的测试驱动开发。一次构建一个垂直切片的功能或修复一个 bug。
domain-modeling: 主动构建并打磨项目的领域模型：对照术语表质疑术语，用边缘场景进行压力测试，并就地更新 GLOSSARY.md 和 ADR。
codebase-design: 设计深度模块的共享纪律和词汇：大量行为隐藏在小接口之后，放置在干净的接缝处，并可通过该接口进行测试。
code-review: 对自固定点以来的 diff 进行双轴审查：标准（是否遵循仓库编码标准，以及 Fowler 坏味道基线？）和规格（是否忠实实现了源 issue/规格？），作为并行子代理运行，使彼此互不污染。
pr: 拉取请求正文应有的形态：一个摘要，作为让变更清晰可见的最小可视化；证明其有效的前后证据；以及合并风险判断（单向门或双向门，外加影响范围）。
wizard: 生成一个交互式 bash 向导，引导人类完成只有他们才能执行的步骤：配置基础设施、设置凭据或 CI 密钥、浏览不熟悉的第三方仪表盘，或运行一次性迁移或切换。

生产力¶

通用工作流工具，不特定于代码。