Matt Pocock Skills 仓库分析报告

01｜结论速览#

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

Matt Pocock 的 0 仓库明确把自己定位为 “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。

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

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、写文档、启动长流程；模型触发技能则像库函数，提供共享词汇和局部纪律。

一个典型组合如下：

用户运行 /improve-codebase-architecture
  ↓
技能要求读取 CONTEXT.md 和 ADR
  ↓
调用 codebase-design 使用深模块词汇
  ↓
输出架构机会 HTML 报告
  ↓
用户选择候选项
  ↓
运行 grilling 进行设计质询
  ↓
必要时调用 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 技能不是泛泛要求“多写测试”，而是把测试工作压成一个红绿重构循环：

Planning
  → 确认 public interface 与优先行为
Tracer Bullet
  → 写一个测试确认一件事
Incremental Loop
  → 每次一个行为，RED → GREEN
Refactor
  → 只在 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-...] 插桩。

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 自动包办所有决策的场景。

12.1｜主要优点#

1. 边界小，易改造。 大多数技能几十行到一百多行，读完即可 fork 修改。
2. 强反馈导向。 TDD、debug、issue slicing 都围绕可验证信号。
3. 尊重项目上下文。 多个技能要求读取 CONTEXT.md 和 ADR，而不是凭空设计。
4. 人类控制关键副作用。 用户触发技能掌管发布 issue、架构评审、PRD、triage 等大动作。
5. 概念语言一致。 codebase-design 与 domain-modeling 为 Agent 提供稳定词汇。

12.2｜主要风险#

1. 依赖项目已有纪律。 如果团队不维护 issue、ADR、CONTEXT，技能效果会下降。
2. 对用户有参与要求。 很多流程需要用户确认、选择、被 grilling；不适合“全自动外包”。
3. 默认偏 Claude Code 生态。 虽然理念可迁移，但安装、插件结构和 frontmatter 约定明显面向 Claude Code。
4. 部分技能仍在草稿或个人区。 in-progress、personal、deprecated 不应无差别采用。
5. HTML 报告能力在仓库内部是目标格式，不是通用渲染器。 真正渲染还依赖本地报告 skill 或项目自己的报告工具。

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

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

13.1｜第一层：直接采用的规则#

• 把技能分成 用户触发 与 模型触发 两类。
• 所有会写外部系统、创建长期约束、启动大流程的技能默认用户触发。
• 所有 debug、TDD、架构分析先建立可验证反馈循环。
• 把领域词汇写成 CONTEXT.md 级别的项目上下文，而不是塞进聊天记忆。

13.2｜第二层：可改造的技能#

• diagnosing-bugs：可改造成我们自己的“失败信号优先”调试 SOP。
• domain-modeling：可与现有长期记忆体系结合，但要保持 glossary-only 的克制。
• codebase-design：可作为架构报告和 refactor 审查的统一词汇。
• to-issues：可用于把复杂需求拆成端到端可验证任务。
• handoff：可与我们当前 working checkpoint / long-term memory 工作流对齐。

13.3｜第三层：谨慎引入的部分#

• triage：需要先映射我们自己的任务状态机，否则容易与既有流程冲突。
• setup-matt-pocock-skills：可参考其探索-确认-写入结构，但不应照搬文件布局。
• improve-codebase-architecture：适合有较大代码库和稳定 ADR 文化的项目；小项目可能过重。

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。 等项目语言和测试反馈稍稳定后，再做架构深挖。

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