给真实工程师的 Skills

我每天用来做实工程——而非 vibe coding——的 agent skill。

开发真实应用很难。GSD、BMAD、Spec-Kit 等方法试图通过「 owning 流程」来帮忙，但与此同时它们会夺走你的控制权，并让流程中的 bug 难以修复。

这些 skill 设计得小而易改、可组合。适用于任何模型。基于数十年工程经验。随意改。变成你的。Enjoy。

若想跟进这些 skill 的变更以及我创建的新 skill，可加入约 60,000 名开发者的 newsletter：

订阅 Newsletter

快速开始（30 秒 setup）

1. 运行 skills.sh 安装器：

npx skills@latest add mattpocock/skills

2. 选择想要的 skill，以及要安装到哪些 coding agent 上。务必选择 /setup-matt-pocock-skills。

3. 在 agent 中运行 /setup-matt-pocock-skills。它会：
   - 询问你想用哪种 issue tracker（GitHub、Linear 或本地文件）
   - 询问分诊时给 ticket 打什么 label（/triage 使用 label）
   - 询问要把我们创建的文档保存在哪里

4. 搞定——可以开始了。

这些 Skill 为何存在

我创建这些 skill，是为了修复我在 Claude Code、Codex 和其他 coding agent 上常见的失败模式。

#1：Agent 没按我想要的方式做

"No-one knows exactly what they want"
（没人确切知道自己要什么）

David Thomas & Andrew Hunt, The Pragmatic Programmer

问题。软件开发最常见的失败模式是 misalignment。你以为 dev 懂你要什么。看到成品后——才发现它根本没理解你。

AI 时代同样如此。你和 agent 之间存在沟通鸿沟。修复方式是 grilling 质询会话——让 agent 就你要构建的内容提出详细问题。

修复是使用：

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

这是我最受欢迎的 skill。它们帮你在开始前与 agent 对齐，并深入思考你要做的变更。_每次_要做变更时都请使用。

#2：Agent 太啰嗦

With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.
（有了通用语言，开发者之间的对话与代码表达都源自同一领域模型。）

Eric Evans, Domain-Driven-Design

问题：项目初期，开发者与他们为之构建软件的人（领域专家）通常说不同的语言。

我对 agent 也有同样感受。Agent 常被丢进项目，被要求边做边搞懂行话。于是 1 个词能说完的，它用 20 个。

修复是共享语言——一份帮助 agent 解码项目行话的文档。

这内建于 /grill-with-docs。它是 grilling 会话，但帮你与 AI 建立共享语言，并将难以解释的决定记入 ADR。

很难形容这有多强大。可能是本 repo 最 cool 的技巧之一。试试就知道。

[!TIP]
共享语言除减少啰嗦外还有许多好处：

• 变量、函数和文件命名一致，使用共享语言
• 因此 代码库对 agent 更易导航
• agent 思考时 token 更少，因为它有更简洁的语言可用

#3：代码跑不通

"Always take small, deliberate steps. The rate of feedback is your speed limit. Never take on a task that's too big."
（始终小步 deliberate。反馈速率是你的速度上限。不要接过大的任务。）

David Thomas & Andrew Hunt, The Pragmatic Programmer

问题：假设你和 agent 已对齐要构建什么。agent _仍然_产出垃圾怎么办？

该审视反馈循环了。若没有关于产出代码实际如何运行的反馈，agent 等于盲飞。

修复：需要 usual 反馈循环：静态类型、浏览器访问、自动化测试。

对自动化测试，红-绿-重构循环至关重要。agent 先写失败测试，再修到通过。这给 agent 一致的反馈水平，产出好得多的代码。

我构建了 /tdd skill，可插入任何项目。它鼓励红-绿-重构，并给 agent 大量关于好测试与坏测试的指导。

调试方面，还有 /diagnose skill，将最佳调试实践包装成简单循环。

#4：我们造了一团泥

"Invest in the design of the system every day."
（_每天_投资系统设计。）

Kent Beck, Extreme Programming Explained

"The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."
（最好的 module 是深的。大量功能可通过简单 interface 访问。）

John Ousterhout, A Philosophy Of Software Design

问题：多数 agent 构建的应用复杂难改。agent 能大幅加速编码，也会加速软件熵。代码库以空前速度变复杂。

修复是对 AI 驱动开发的 radical 新思路：关心代码设计。

这内建于这些 skill 的每一层：

• /to-prd 在创建 PRD 前会 quiz 你触及哪些 module
• /zoom-out 让 agent 在 whole system 语境下解释代码

关键的是，/improve-codebase-architecture 帮你 rescue 已成一团泥的代码库。建议每隔几天在代码库上运行一次。

总结

软件工程 fundamentals 比以往更重要。这些 skill 是我将这些 fundamentals condensed 成可重复实践的最佳努力，帮你 ship 职业生涯中最好的应用。Enjoy。

Reference（参考）

Engineering

我日常用于代码工作的 skill。

• diagnose — 针对难 bug 与性能回归的 disciplined 诊断循环：复现 → 最小化 → 假设 → 插桩 → 修复 → 回归测试。
• grill-with-docs — grilling 质询会话，对照现有领域模型挑战计划、 sharpen 术语，并 inline 更新 CONTEXT.md 与 ADR。
• triage — 通过分诊角色状态机分诊 issue。
• improve-codebase-architecture — 在代码库中寻找 deepening 机会， informed by CONTEXT.md 中的领域语言与 docs/adr/ 中的决定。
• setup-matt-pocock-skills — scaffold 其他 engineering skill 消费的 per-repo 配置（issue tracker、分诊 label 词汇表、领域文档布局）。每个 repo 运行一次，再使用 to-issues、to-prd、triage、diagnose、tdd、improve-codebase-architecture 或 zoom-out。
• tdd — 红-绿-重构循环的测试驱动开发。一次一个垂直切片构建功能或修 bug。
• to-issues — 用垂直切片将任意计划、spec 或 PRD 拆成可独立 grab 的 GitHub issue。
• to-prd — 将当前对话上下文转为 PRD 并提交为 GitHub issue。无 interview——仅 synthesize 已讨论内容。
• zoom-out — 让 agent zoom out，对 unfamiliar 代码段给出 broader 语境或更高层视角。
• prototype — 构建可丢弃 prototype 以 flesh out 设计——要么是 state/业务逻辑问题的可运行终端 app，要么是从单一路由可切换的多种 radically 不同 UI 变体。

Productivity

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

• caveman — ultra-compressed 沟通模式。去掉 filler 将 token 用量削减约 75%，同时保持完整技术准确性。
• grill-me — 就计划或设计被 relentless interview，直到决策树每个分支 resolved。
• handoff — 将当前对话 compact 成 handoff 文档，供另一 agent 继续工作。
• teach — 跨多 session 教用户新 skill 或概念，以当前目录为 stateful 教学 workspace。
• write-a-skill — 创建结构正确、渐进披露、bundled resources 的新 skill。

Misc

保留备用但很少使用的工具。

• git-guardrails-claude-code — 设置 Claude Code hooks，在 push、reset --hard、clean 等危险 git 命令执行前 block。
• migrate-to-shoehorn — 将测试文件从 as 类型断言迁移到 @total-typescript/shoehorn。
• scaffold-exercises — 创建含 section、problem、solution 与 explainer 的练习目录结构。
• setup-pre-commit — 设置 Husky pre-commit hooks，含 lint-staged、Prettier、类型检查与测试。