以下是您可以在任何 TypeScript 代码库中运行一次的技能，用于设置深层模块：

• 每个“包”位于 src/packages/（名称/路径完全可自定义）
• 从包外部只能通过 /index.ts 导入
• 包的测试位于 /tests 目录，且只能从 index.ts 导入
• 包之间无循环依赖
• 在 AGENTS.md 中放置一个上下文指针，让 agent 知道它的存在（无需技能）
• 支持前端或后端代码（甚至支持 Effect 代码！）
• 由 dependency-cruiser 强制执行

这意味着你可以将内容隐藏在模块内部，只暴露一个测试接缝。清晰的接缝，确定性强制：不再有糟糕的测试。正在等待合并。我应该发布它吗？

mattpocock/skills

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

面向真正工程师的技能

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

我每天用于实际工程（而非氛围编码）的 agent 技能。

开发真实应用是困难的。像 GSD、BMAD 和 Spec-Kit 这样的方法试图通过掌控流程来提供帮助，但这样做却夺走了你的控制权，并使流程中的错误难以解决。

这些技能设计得小巧、易于调整且可组合。它们适用于任何模型。它们基于数十年的工程经验。随意修改它们，让它们成为你自己的。享受吧。

如果你想了解这些技能的变化以及我创建的任何新技能，可以加入我的 newsletter，已有约 60,000 名开发者订阅：
订阅 Newsletter

快速开始（30 秒设置）

1. 运行 skills.sh 安装程序：
   bash npx skills@latest add mattpocock/skills

2. 选择你想要的技能，以及你想安装它们的编码 agent。请务必选择 /setup-matt-pocock-skills。

3. 在 agent 中运行 /setup-matt-pocock-skills。它会：

   • 询问你想使用哪个问题跟踪器（GitHub、Linear 或本地文件）
   • 询问你在分类 ticket 时应用的标签（/triage 使用标签）
   • 询问你想将我们创建的任何文档保存在哪里

4. 搞定——准备就绪。

这些技能为何存在

我构建这些技能是为了修复我在 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 相同，但增加了更多功能（见下文）

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

#2：Agent 过于啰嗦

“有了通用语言，开发者之间的对话和代码的表达都来自同一个领域模型。”
Eric Evans，《领域驱动设计》(https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)

问题：项目开始时，开发者和为其构建软件的人（领域专家）通常说着不同的语言。我在 agent 身上也感受到了同样的紧张。Agent 通常被直接丢进项目，要求他们边做边弄懂行话。所以他们用 20 个词来说一个词就能表达的事。

解决方法：共享语言。这是一份文档，帮助 agent 解码项目中使用的行话。

示例：这是我 course-video-manager 仓库中的一个 CONTEXT.md 示例 (https://github.com/mattpocock/course-video-manager/blob/076a5a7a182db0fe1e62971dd7a68bcadf010f1c/CONTEXT.md)。哪个更容易阅读？

• 之前：“当课程某部分中的某个课程变得‘真实’（即在文件系统中获得一个位置）时，会出现一个问题”
• 之后：“物化级联出现问题”

这种简洁性会在每次会话中得到回报。这已经内置在 /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 将盲目飞行。

解决方法：你需要常见的反馈循环：静态类型、浏览器访问和自动化测试。对于自动化测试，红-绿-重构循环至关重要。这是 agent 先编写一个失败的测试，然后修复该测试的过程。这有助于给 agent 提供一致的反馈水平，从而产生更好的代码。

我构建了一个 /tdd 技能，可以插入任何项目。它鼓励红-绿-重构，并为 agent 提供关于什么构成好测试和坏测试的充分指导。

对于调试，我还构建了一个 /diagnosing-bugs 技能，将最佳调试实践封装成一个简单的循环。

#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 可以极大加速编码，它们也加速了软件熵。代码库以前所未有的速度变得复杂。

解决方法：一种激进的新方法：关心代码的设计。这内置于这些技能的每一层：

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

关键是，/improve-codebase-architecture 帮助你拯救一个已经成为泥球的代码库。我建议每隔几天在你的代码库上运行它。

总结

软件工程基础比以往任何时候都更重要。这些技能是我尽最大努力将这些基础浓缩成可重复的实践，帮助你构建职业生涯中最好的应用。享受吧。

参考

这些技能根据一个维度进行划分——谁可以调用它们。

用户调用的技能只有在你键入时才能使用（例如 /grill-me）；它们的工作是编排。

模型调用的技能可以由你调用，也可以由 agent 在任务匹配时自动调用；它们持有可重用的纪律。

用户调用的技能可以调用模型调用的技能，但永远不会调用另一个用户调用的技能。

工程技能

我每天用于代码工作。

用户调用

• ask-matt — 询问哪种技能或流程适合你的情况。此仓库中用户调用技能的路由器。
• grill-with-docs — 盘问会话，同时构建项目的领域模型，锐化术语，并内联更新 CONTEXT.md 和 ADR。
• triage — 通过分诊角色的状态机移动问题。
• improve-codebase-architecture — 扫描代码库以寻找深化机会，将其呈现为可视化的 HTML 报告，然后对你选择的每个机会进行盘问。
• setup-matt-pocock-skills — 为工程技能配置此仓库（问题跟踪器、分诊标签、领域文档布局）。每个仓库运行一次，然后再使用其他工程技能。
• to-spec — 将当前对话转变为规范并发布到问题跟踪器。无需访谈——只需综合你已经讨论过的内容。
• to-tickets — 将任何计划、规范或对话分解为一组追踪弹 ticket，每个 ticket 声明其阻塞边——作为本地文件中的文本，或作为真实跟踪器上的原生阻塞链接编写。
• implement — 构建由规范或一组 ticket 描述的工作，在预先商定的接缝处驱动 /tdd，并在提交前以 /code-review 收尾。
• wayfinder — 计划一个大的工作块，超过一个 agent 会话所能容纳，作为问题跟踪器上的共享调查 ticket 地图——一次解决一个，直到到达目的地的路径清晰。

模型调用

• prototype — 构建一个可丢弃的原型来回答设计问题——一个可运行的终端应用用于状态/逻辑问题，或几个风格迥异的 UI 变体，可以通过一条路由切换。
• diagnosing-bugs — 针对顽固错误和性能回归的严格诊断循环：重现 → 最小化 → 假设 → 检测 → 修复 → 回归测试。
• research — 针对高信任度主要来源调查一个问题，并将发现作为带引用的 Markdown 文件捕获到仓库中，作为后台 agent 运行。
• tdd — 带有红-绿-重构循环的测试驱动开发。一次一个垂直切片地构建功能或修复错误。
• domain-modeling — 积极构建和锐化项目的领域模型——对照词汇表挑战术语，用边缘案例场景进行压力测试，并内联更新 CONTEXT.md 和 ADR。
• codebase-design — 用于设计深层模块的共享纪律和词汇：小接口背后的许多行为，放在清晰的接缝处，通过该接口可测试。
• code-review — 对自固定点以来的差异进行两轴审查：标准（是否遵循仓库的编码标准，加上 Fowler 代码坏味基线）和规范（是否忠实地实现了源发问题/PRD），作为并行子 agent 运行，避免互相污染。

生产力

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

用户调用

• grill-me — 就计划或设计接受无情的盘问，直到决策树的每个分支都被解决。
• handoff — 将当前对话压缩成一份交接文档，以便另一个 agent 可以继续工作。
• teach — 通过多次会话教授用户新技能或概念，使用当前目录作为有状态的教学工作区。
• writing-great-skills — 关于如何良好编写和编辑技能的参考：使技能具有可预测性的词汇和原则。

模型调用

• grilling — 就计划或设计无情地盘问用户，直到决策树的每个分支都被解决。grill-me 和 grill-with-docs 背后的可重用循环。