Matt Pocock Skills 仓库分析报告

01｜结论速览#

这个仓库不是“提示词大全”，而是一套把资深工程师工作习惯压缩成可组合 Agent 技能的操作系统。

Matt Pocock 的 mattpocock/skills 仓库明确把自己定位为 “Skills For Real Engineers”：用于真实工程，而不是 vibe coding。README 的核心论点很清楚：大型流程框架会替用户“拥有流程”，但也会让调试流程本身变困难；这个仓库反过来选择小而可改、可组合、可嫁接到任意模型的技能单元。

本次拉取并分析的仓库状态如下：

[INSIGHT] 这个项目最值得学习的不是某一个 prompt，而是它的“技能边界设计”：用户触发的技能负责流程入口与授权，模型触发的技能负责共享语言、诊断循环、TDD 等可复用子能力。

如果只用一句话概括：它把 Agent 从“会写代码的聊天机器人”推向“遵守工程纪律的协作工程师”。

02｜仓库定位：反框架、重反馈、强领域语言#

README 开篇用了一个对比：GSD、BMAD、Spec-Kit 这类方案试图“拥有流程”，而 skills 仓库强调 small, easy to adapt, composable。这不是营销措辞，它贯穿了仓库结构：每个技能都很短，通常只有几十到一百多行 Markdown；复杂工作通过技能之间的调用关系连接，而不是塞进一个巨型主 prompt。

仓库安装路径也体现了这种思路：

1
npx skills@latest add mattpocock/skills

安装后特别要求用户选择并运行 /setup-matt-pocock-skills。这一步不是样板初始化，而是在目标项目中建立三个后续技能默认依赖的“工程上下文”：

1. Issue tracker：问题和工作项在哪里；默认支持 GitHub，也支持本地 Markdown、GitLab 或其他工具。
2. Triage labels：五类 triage 角色如何映射到项目自己的标签。
3. Domain docs：CONTEXT.md、CONTEXT-MAP.md 和 ADR 的布局约定。

这说明仓库的基本假设是：Agent 想稳定地产出工程价值，不能只靠上下文窗口里的对话；它需要读取项目已有语言、尊重既有架构决策，并把新决策写回项目。

03｜技能清单与分层#

仓库按 bucket 管理技能，但真正的分层是“正式插件技能”和“个人/草稿/弃用技能”。

本地解析到 34 个 SKILL.md，分布如下：

.claude-plugin/plugin.json 当前正式暴露 17 个技能，主要来自 engineering 和 productivity：

这个清单里有一个很重要的设计：正式入口多是用户触发，核心工程纪律多是模型触发。 这让人类保留“什么时候开始一个流程”的控制权，同时让模型在流程内部自动调用可复用纪律。

04｜调用模型：User-invoked 与 Model-invoked 的边界#

仓库文档把所有 SKILL.md 分成两类：

• User-invoked：只有人类明确输入技能名才能触达；frontmatter 设置 disable-model-invocation: true。
• Model-invoked：模型可以在需要时主动使用，也可被人类直接要求使用。

这个边界非常关键。用户触发技能通常会产生外部副作用、改变项目状态、发布 issue、写文档、启动长流程；模型触发技能则像库函数，提供共享词汇和局部纪律。

一个典型组合如下：

1
用户运行 /improve-codebase-architecture
2
  ↓
3
技能要求读取 CONTEXT.md 和 ADR
4
  ↓
5
调用 codebase-design 使用深模块词汇
6
  ↓
7
输出架构机会 HTML 报告
8
  ↓
9
用户选择候选项
10
  ↓
11
运行 grilling 进行设计质询
12
  ↓
13
必要时调用 domain-modeling 更新 CONTEXT 或 ADR

[NOTE] 这套调用模型避免了一个常见失败：Agent 自己“决定要重构架构”并大规模改代码。仓库把大动作放在用户触发技能中，把分析与词汇放在模型触发技能中。

从本地 Agent 工作流角度看，这个规则值得直接借鉴：任何会写入外部系统、重排工作项、产生长期约束的技能，都应该默认用户触发；任何只提供判断框架和局部反馈循环的技能，才适合模型自动触发。

05｜工程主线一：先建项目上下文，再让 Agent 工作#

/setup-matt-pocock-skills 是整个工程技能组的入口。它不会假设项目已经使用 GitHub、不会强行创建 AGENTS.md 或 CLAUDE.md，而是要求先探索：

• git remote -v 与 .git/config：判断是否是 GitHub repo。
• 根目录 AGENTS.md、CLAUDE.md：是否已有 Agent 规则。
• CONTEXT.md、CONTEXT-MAP.md：是否已有领域语言。
• docs/adr/ 与 src/*/docs/adr/：是否已有架构决策记录。
• .scratch/：是否已有本地 Markdown issue convention。

然后它要求逐项向用户确认三类决策：issue tracker、triage labels、domain docs。最后只在合适的位置更新一个 ## Agent skills 块，并写入 docs/agents/*.md。

这里体现了一个成熟工程原则：Agent 不应先做事再解释，而应先发现既有约定，再最小写入约定。

06｜工程主线二：领域语言是 token 压缩器，也是质量护栏#

README 把 domain-modeling 称为“这个仓库里最酷的技术之一”。该技能的核心是建立项目自己的 ubiquitous language：把用户、代码、issue、测试、ADR 用同一套词汇连起来。

domain-modeling 不只是写 glossary。它要求在会话中持续执行四件事：

1. 挑战冲突术语：如果用户说的词与 CONTEXT.md 定义冲突，立即指出。
2. 锐化模糊语言：例如“account”到底是 Customer 还是 User。
3. 讨论具体场景：用边界案例逼出概念关系。
4. 与代码交叉验证：如果代码行为与用户叙述冲突，要显式暴露。

它还明确规定 CONTEXT.md 不是 spec、不是草稿、不是实现记录；它只能是 glossary。ADR 也不能滥写，只有在“难以逆转、无上下文会惊讶、确实存在真实取舍”三项同时满足时才建议写。

[INSIGHT] 这比普通“项目记忆”更严格：它不保存所有信息，只保存能稳定降低未来沟通成本的概念边界。

对于我们自己的 Agent 体系，这一点尤其有价值。长期记忆容易膨胀为杂物箱，而 domain-modeling 给出了一条更窄的标准：只有能命名、能区分、会被反复使用的领域概念，才应进入项目上下文。

07｜工程主线三：深模块词汇把架构讨论变成可执行判断#

codebase-design 提供了仓库最重要的架构语言。它要求准确使用这些词，而不要混用 component、service、API、boundary：

该技能还给出三个判断原则：

1. 删除测试：如果删掉测试仍能通过类型/接口获得信心，模块更可能是深的。
2. 接口就是测试表面：接口越小，测试越自然。
3. 一个 adapter 是假想 seam，两个 adapter 才是真 seam：只有当同一 interface 有多个实现时，seam 才真正经受了抽象检验。

这套词汇让架构建议不再是“这个 service 太乱”“这里需要抽象”这种模糊评价，而能变成更具体的问题：这个 module 的 interface 是否暴露了太多实现细节？这个 seam 是否只有一个 adapter 因而只是自我安慰？这个重构能提高 locality 还是只是在移动代码？

08｜工程主线四：TDD 与诊断技能都围绕“反馈循环”#

tdd 技能不是泛泛要求“多写测试”，而是把测试工作压成一个红绿重构循环：

1
Planning
2
  → 确认 public interface 与优先行为
3
Tracer Bullet
4
  → 写一个测试确认一件事
5
Incremental Loop
6
  → 每次一个行为，RED → GREEN
7
Refactor
8
  → 只在 GREEN 时重构

它强调测试行为而非实现，使用 public interface，不为未来测试预写 speculative code。

diagnosing-bugs 更鲜明：第一阶段叫 Build a feedback loop，并且写明“这就是这个技能”。它认为只要有一个针对该 bug 的紧密红/绿信号，后面的二分、假设、插桩都只是消费这个信号；如果没有，再怎么盯代码也没用。

可构建反馈循环的手段从失败测试、curl/HTTP 脚本、CLI fixture、headless browser、trace replay、throwaway harness、property/fuzz loop，一直到 bisect harness。修复阶段要求先把最小复现变成 regression test，再修复，并最终清理所有 [DEBUG-...] 插桩。

[WARNING] 很多 Agent debug 失败不是因为模型不会读代码，而是因为它没有先构造可重复的失败信号。这个仓库把“反馈循环”提升为首要工程对象，这是它能区别于普通 prompt 库的关键。

09｜工作项体系：从 PRD 到 tracer-bullet issue#

/to-prd 与 /to-issues 负责把对话和计划转为可执行工作。尤其 /to-issues 明确要求用 vertical slices / tracer bullets 拆分，而不是按层拆分。

它的规则是：

• 每个 slice 都要穿透所有集成层：schema、API、UI、tests。
• 完成后必须可 demo 或可独立验证。
• 如果需要 prefactoring，应该先做：“Make the change easy, then make the easy change.”
• 发布 issue 时只描述端到端行为和验收标准，避免易过期的文件路径和代码片段。

这种拆分方式很适合 AFK agents：每张 issue 都是一个狭窄但完整的价值路径，不会让一个 Agent 只改数据库、另一个 Agent 只改 UI，最后没人负责端到端行为。

10｜架构改进流程：先报告，再选择，再 grilling#

/improve-codebase-architecture 是最接近本次用户要求“给我一个 HTML 报告”的技能。它的流程很像一次受控架构评审：

1. 先读 CONTEXT.md 与相关 ADR。
2. 用探索型子 Agent 遍历代码库，记录真实理解摩擦。
3. 输出 visual HTML report，列出 deepening opportunities。
4. 不立即提出接口方案，而是先问用户选择哪个机会。
5. 对选中的候选项运行 /grilling，再在决策明确时更新领域模型或 ADR。

最有价值的是第 4 点：报告只负责发现机会，不负责直接开刀。 这能避免 Agent 在“看起来发现问题”后直接进入大规模重构，也保留了人类对优先级和风险的控制权。

11｜Productivity 技能：把 Agent 协作变成可交接、可教学、可审问#

productivity bucket 中的技能并不写代码，但对团队使用 Agent 很关键：

• /grill-me：对计划或设计进行无情面试，防止过早实现。
• grilling：模型可调用的追问纪律。
• /handoff：把当前对话压缩成另一个 Agent 可接手的文档。
• /teach：在 workspace 内教学，不只是解释概念。
• /writing-great-skills：如何写好技能本身的元技能。

其中 /writing-great-skills 值得单独提：它要求 description 既要说明“何时使用”，也要控制信息层级，避免技能膨胀。换句话说，这个仓库不仅提供技能，也提供维护技能的方法论。

12｜优点、风险与适用边界#

这套技能非常适合有工程纪律的团队，但不适合期待 Agent 自动包办所有决策的场景。

13｜对我们本地 Agent 体系的借鉴建议#

结合本次分析，我建议按三层引入，而不是全量照搬。

14｜推荐落地顺序#

如果要在一个真实项目中试用，我会按如下顺序：

1. 创建或清理 CONTEXT.md。 只写 glossary，不写实现细节。
2. 补 docs/agents/ 约定。 记录 issue tracker、triage labels、domain docs 位置。
3. 先使用 diagnosing-bugs 和 tdd。 它们最容易产生即时质量收益。
4. 再使用 to-issues。 把大需求切成 tracer-bullet vertical slices。
5. 最后使用 improve-codebase-architecture。 等项目语言和测试反馈稍稳定后，再做架构深挖。

[TIP] 不要从“架构改造”开始。先从 bug 诊断和 TDD 开始，因为它们能最快建立团队对 Agent 工程纪律的信任。

15｜最终评价#

mattpocock/skills 的价值不在于“让 Agent 更聪明”，而在于让 Agent 更像一个受约束的工程协作者：先读项目语言，先构造反馈循环，先拆端到端小切片，先问清楚再写入长期决策。

它对当前 AI 编程工具生态的启发是：

• prompt 不应该无限变长，应该被拆成技能；
• 技能不应该全都自动触发，应该区分授权边界；
• Agent 不应该只优化代码生成，应该优化反馈速度、术语一致性和决策可追溯性；
• 工程能力不是“模型能力”的同义词，而是模型、项目文档、测试反馈、issue tracker、用户确认共同组成的系统。

因此，这个仓库非常值得长期关注，也适合作为我们构建自有 SOP / skills 体系的参考样板。但最好的使用方式不是照搬全部文件，而是学习它的边界设计与反馈循环，把其中的工程纪律移植到自己的项目环境中。

16｜附录：本次核验来源#

• 本地克隆仓库：/Users/a11/2026/2026511-611/GenericAgent/temp/repos/skills
• GitHub 仓库：https://github.com/mattpocock/skills
• 关键文件：README.md
• 关键文件：docs/invocation.md
• 关键文件：CONTEXT.md
• 关键文件：.claude-plugin/plugin.json
• 关键技能：skills/engineering/setup-matt-pocock-skills/SKILL.md
• 关键技能：skills/engineering/domain-modeling/SKILL.md
• 关键技能：skills/engineering/codebase-design/SKILL.md
• 关键技能：skills/engineering/tdd/SKILL.md
• 关键技能：skills/engineering/diagnosing-bugs/SKILL.md
• 关键技能：skills/engineering/to-issues/SKILL.md
• 辅助清单：reports/skills_inventory.json