mattpocock 发布面向真实工程的 AI 编程 Agent Skills

我每天用来做真正工程的 Agent Skill——不是 Vibe Coding。

开发真正的应用很难。GSD、BMAD、Spec-Kit 这类方法想通过接管流程来帮忙，但代价是你失去了控制权，流程里出了问题也很难排查。

这些 Skill 刻意做得很小、容易改、可以自由组合，适配任何模型，背后是几十年的工程经验。随便折腾，改成你自己的，用得开心。

安装（30 秒搞定）

两种装法，两种思路。Claude Code 插件把整套 Skill 作为一个受管的只读包安装，我发布新版本时会自动更新，所以你是在订阅，而不是 fork。skills.sh则把可编辑的 Skill 文件复制进你的项目，你可以随便改、改成自己的。二选一：两个都装，每个 Skill 都会出现两份。

1. 获取 Skill

Claude Code

claude plugins install mattpocock-skills

或者在会话里直接执行：

/plugin install mattpocock-skills

它已经在 Claude Code 官方市场里，不需要先添加什么，更新也会自动推送。

Codex 及其他 Agent

npx skills@latest add mattpocock/skills

挑你想要的 Skill，再选装到哪些编码 Agent 上。安装器会让你自己选装哪些 Skill，务必把 setup-matt-pocock-skills 选上。

原生 Codex 插件已在计划中（见 .agents/adr/0002-ship-as-a-claude-code-plugin.md）。

给爱折腾的人

还是用同一个安装器，任何 Agent 都行，包括 Claude Code：

npx skills@latest add mattpocock/skills

它会把 Skill 以普通文件的形式写进你的仓库，归你所有、随你编辑。不会有任何东西在背后偷偷更新；想要我的最新改动时，用 npx skills update 拉一下就行。

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

在你的 Agent 里，每个仓库跑一次。它会：

问你用哪个 issue 追踪系统（GitHub、Linear 或本地文件）
问你在分类工单时会打哪些标签（/triage 用的是标签）
问你想把我们生成的文档存到哪里

3. 搞定——可以开工了。

这些 Skill 为什么存在

我做这些 Skill，是为了解决我在 Claude Code、Codex 和其他编码 Agent 上常见的几类翻车场景。

#1：Agent 没按我想的做

“没有人真正清楚自己想要什么”

David Thomas & Andrew Hunt，《程序员修炼之道》

问题。软件开发里最常见的翻车方式就是没对齐。你以为开发知道你想要什么，等看到做出来的东西，才发现它压根没理解你。

到了 AI 时代也一样。你和 Agent 之间存在沟通鸿沟。解法就是来一场盘问会——让 Agent 就你要做的东西追问细节。

解法是用：

/grill-me——用于非代码场景
/grill-with-docs——和 /grill-me 一样，但多了些好东西（见下文）

这两个是我最受欢迎的 Skill。它们能在动手之前帮你和 Agent 对齐，并深入思考这次改动。每次想改点什么，都务必用上。

#2：Agent 太啰嗦了

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

Eric Evans，《领域驱动设计》

问题：项目刚开始时，开发者和他们要服务的人（领域专家）通常说的不是同一种语言。

我的智能体也有同样的困扰。智能体通常被直接丢进项目里，一边干活一边猜那些黑话是什么意思。结果就是，本来1个词能说清的事，它非要用20个词。

解决办法是建立一套共享语言。用一份文档帮智能体解读项目里的黑话。

示例

下面是我course-video-manager仓库里的一份词汇表示例（在那个固定提交里还叫CONTEXT.md，那时 Skill 还没改掉这个命名）。哪个更好读？

之前：“当课程某个章节里的一节课被‘真实化’（也就是在文件系统里给它分配一个位置）时，会出问题。”
之后：“物化级联出了问题。”

这种简洁的表达，一次会话接一次会话地省下成本。

这已经内置在/grill-with-docs里了。过程像是一场盘问，但正是这样能帮你和 AI 建立共享语言，并把那些难以解释的决策写进 ADR。

很难说清这有多强大。这可能是这个仓库里最酷的一招。试试看就知道了。

小贴士

共享语言除了减少啰嗦，还有很多其他好处：

变量、函数和文件的命名更一致，都基于这套共享语言
因此，智能体更容易在代码库里找到方向
智能体花在思考上的 token 也更少，因为它能用上更精炼的语言

#3：代码跑不起来

“始终迈小而谨慎的步子。反馈速度就是你的速度上限。永远不要接下过大的任务。”

David Thomas & Andrew Hunt，《程序员修炼之道》

问题：假设你和智能体已经对齐了要做什么。可它还是写出一堆烂代码，怎么办？

这时候该看看你的反馈回路了。如果拿不到代码实际运行情况的反馈，智能体就是在盲飞。

解决办法：你需要常规的那几层反馈回路：静态类型、浏览器访问、自动化测试。

自动化测试这块，红绿重构循环是关键。也就是让智能体先写一个失败的测试，再去修。这样能给智能体稳定的反馈，写出来的代码好得多。

我做了个/tdd Skill，可以直接放进任何项目。它会推动红绿重构，并给智能体大量关于什么是好测试、什么是坏测试的指导。

调试方面，我还做了个/diagnosing-bugs Skill，把最佳调试实践包成一套有纪律的循环，逐阶段设卡。

#4：我们造出了一团泥球

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

Kent Beck，《解析极限编程》

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

John Ousterhout，《软件设计哲学》

问题：大多数用智能体构建的应用既复杂又难改。智能体能大幅加快编码速度，也就加速了软件熵增。代码库正以前所未有的速度变复杂。

解决办法是换一种全新的 AI 开发思路：真正在意代码的设计。

这一点已经融入这些 Skill 的每一层：

/to-spec会在你写规格之前，先问你正在动哪些模块

更关键的是，/improve-codebase-architecture 会扫描代码库，找出可以深化的地方，把候选点列给你。我建议每隔几天就在自己的代码库上跑一次。它是调研，不是救火：在一个确实很老的代码库里，它能找到真实的候选点，但不会替你把这团乱麻理顺。

总结

软件工程的基本功比以往任何时候都更重要。这些技能是我尽力把这些基本功提炼成可重复实践的结果，帮你做出职业生涯中最好的应用。希望你喜欢。

参考

它们的区别只有一个维度：谁能调用。 用户调用型技能只有你手动输入时才能触发（例如 /grill-me），职责是编排流程。 模型调用型技能既可以由你调用，也可以在任务匹配时由编程智能体自动调用，承载的是可复用的规范。用户调用型技能可以调用模型调用型技能，但绝不能调用另一个用户调用型技能。

工程实践

我日常写代码时用的技能。

用户调用型

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

模型调用型

prototype：搭一个用完即弃的原型来回答某个设计问题，可以是单个可分享的 HTML 文件，用来回答状态/逻辑问题；也可以是几个截然不同的 UI 方案，通过一条路由切换。
diagnosing-bugs：针对疑难 Bug 和性能回归的严谨诊断闭环：先搭一个能在这个 Bug 上变红的反馈循环 → 最小化 → 提出假设 → 加探针 → 修复 → 回归测试。
research：围绕某个问题查阅高可信度的一手资料，把结论整理成带引用的 Markdown 文件放进仓库，以后台 Agent 的方式运行。
tdd：红-绿-重构的测试驱动开发。每次只做一个垂直切片，用来开发功能或修 Bug。
domain-modeling：主动构建并打磨项目的领域模型：拿术语对照词汇表，用边界场景做压力测试，并同步更新 GLOSSARY.md 和 ADR。
codebase-design：设计深模块的通用规范和词汇：小接口背后藏着大量行为，放在干净的接缝处，并且能通过这个接口测试。
code-review：从固定基准点开始，对 diff 做两个维度的评审：标准（是否遵循仓库的编码规范，另外对照 Fowler 的坏味道基线？）和规格（是否忠实实现了最初的 issue/规格？）。两个维度作为并行子 Agent 运行，互不污染。
pr：PR 正文该有的样子：用最小的可视化摘要把改动讲清楚，附上改动前后的效果证据，再给出合并风险判断（单向门还是双向门，以及影响范围）。
wizard：生成一个交互式 bash 向导，带着人一步步完成只有他们才能做的事：开通基础设施、配置凭据或 CI secret、摸索陌生的第三方控制台，或者执行一次性的迁移或割接。

生产力

通用工作流工具，不针对具体代码。

用户触发

grill-me：针对某个方案或设计被反复追问，直到设计树上的每个分支都有结论。
handoff：把当前对话压缩成一份交接文档，让另一个 Agent 能接着往下做。
teach：分多次会话教用户一项新技能或概念，把当前目录当作有状态的教学工作区。
to-questionnaire：把你自己答不了的决策变成一份 Markdown 问卷，交给唯一能答的人，可以异步填，也可以开会一起填。它追问的是怎么发出去（发给谁、要拿回什么），而不是问卷主题本身。
wait-what：一旦某条消息没让人看懂，立刻用它。Agent 会用大白话、结合你缺的上下文，拿你熟悉的 GLOSSARY.md 词汇重新讲一遍。

模型触发

grilling：针对某个方案、决策或想法反复追问用户，直到设计树上的每个分支都有结论。这是 grill-me、grill-with-docs、triage、wayfinder 和 improve-codebase-architecture 背后可复用的追问原语。
writing-for-agents：写给 Agent 看的文档：Skill、AGENTS.md/CLAUDE.md，以及任何 Agent 通过指针找到的文档。