基于 main@885e2ca。仓库共有 35 个 SKILL.md：25 个正式发布、6 个 in-progress、4 个 misc。正式集合又分为 14 个用户触发型和 11 个模型触发型。

先理解调用模型

• 用户触发型：Frontmatter 带 disable-model-invocation: true，Codex 元数据还应带 policy.allow_implicit_invocation: false。只能由人主动启动，通常负责编排、确认和可能改变项目状态的流程。
• 模型触发型：人和模型都能启动，通常承载可复用的工程纪律。
• 依赖规则：用户触发型可以调用模型触发型，但不能调用另一个用户触发型。需要用户先做的步骤只能提醒，不能暗中代执行。

---

一、正式工程 Skills

1. ask-matt

类型：用户触发型。

解决的问题：仓库里的 Skill 很多，用户不该背下全部名字。ask-matt 是总路由器，根据当前处境推荐入口和后续路径。

主要流程：

• 新需求：grill-with-docs → to-spec/to-tickets → implement；
• 难 Bug：diagnosing-bugs；
• 外部 Issue 堆积：triage；
• 跨多会话的大型模糊工作：wayfinder；
• 日常架构保养：improve-codebase-architecture；
• 不在仓库里的想法：grill-me。

它还解释上下文边界：继续当前会话、clear、handoff、子 Agent 和 compact 分别适合什么情况。

产物：不直接修改代码，只给出流程选择。

边界：它是导航页，不负责替代被推荐的 Skill。使用工程流程前通常要先运行 setup-matt-pocock-skills。

2. setup-matt-pocock-skills

类型：用户触发型，每个仓库首次使用时运行。

解决的问题：to-spec、triage、wayfinder 等流程需要知道 Issue 存在哪里、分诊标签叫什么、领域文档放哪里。

执行过程：

1. 检查 Git 远端、AGENTS.md/CLAUDE.md、CONTEXT.md、ADR、.scratch/ 和 monorepo 信号；
2. 推荐 GitHub、GitLab、本地 Markdown 或自定义 Issue Tracker；
3. 若安装了 triage，确认五个标签：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix；
4. 普通项目默认使用单一 CONTEXT.md + docs/adr/；大型 monorepo 才考虑 CONTEXT-MAP.md；
5. 先展示草稿，用户确认后再写文件。

产物：docs/agents/issue-tracker.md、domain.md、可选的 triage-labels.md，以及 AGENTS.md 或 CLAUDE.md 中的 ## Agent skills 区块。

边界：它不是固定脚本，不应没检查仓库就机械生成文件；已有 CLAUDE.md 时不能另建 AGENTS.md。

3. grill-with-docs

类型：用户触发型。

解决的问题：在真实仓库里澄清需求，同时让澄清结果能被后续会话复用。

内部机制：它本身只有几行，组合两个模型触发型 Skill：

grilling + domain-modeling

grilling 负责沿决策树访谈，domain-modeling 负责同步术语、场景和必要的 ADR。

产物：对话中的明确决策、更新后的 CONTEXT.md，以及少量真正值得保留的 ADR。

边界：只要有工作目录，它通常优于无状态的 grill-me；但字段改名、简单文案等低风险工作不值得跑完整访谈。

4. triage

类型：用户触发型。

解决的问题：把未经整理的外部 Issue 或 PR 变成维护者可以处理的状态，而不是让 Agent 直接照着模糊报告开工。

状态模型：

• needs-triage：还没判断；
• needs-info：缺少可行动信息；
• ready-for-agent：已经能交给 Agent；
• ready-for-human：需要人的判断、权限或手工验证；
• wontfix：已实现、拒绝或不在范围内。

执行过程：读取完整 Issue/PR、评论、标签和 diff；按领域概念搜索现有实现；检查 .out-of-scope/ 中的历史拒绝；复现 Bug 或验证 PR 声称的行为；必要时运行 grilling + domain-modeling；最后写 Agent brief、追问信息或关闭请求。

产物：标签变化、Agent brief、Triage Notes，或带理由的关闭结论。

边界：只处理外部进入的原始请求。to-tickets 生成的任务已经是 agent-ready，不能再送去 triage。

5. improve-codebase-architecture

类型：用户触发型。

解决的问题：主动发现让代码更易测试、更有局部性、也更方便 Agent 理解的架构改进点。

执行过程：

1. 先读取 codebase-design 的统一词汇；
2. 根据用户指定范围或 Git 热点选择扫描区域；
3. 结合 CONTEXT.md 和 ADR 探索浅模块、泄漏的 seam、分散的逻辑和难测区域；
4. 使用 deletion test 判断抽象是否真的集中复杂度；
5. 输出带 before/after 图的 HTML 报告；
6. 用户选择候选后，用 grilling 继续设计，并用 domain-modeling 同步术语。

产物：临时目录中的架构审查 HTML、候选清单和首选建议。

边界：这是发现机会的 survey，不是自动重构器。报告阶段不应提前发明具体接口。

6. to-spec

类型：用户触发型。

解决的问题：把当前已经讨论清楚的上下文固化成一份可执行规格。

执行过程：检查代码现状和领域文档；优先选择现有测试 seam，尽量使用最高、最少的公开 seam；与用户确认 seam；把已知内容整理成 Problem、Solution、User Stories、Implementation Decisions、Testing Decisions、Out of Scope 和 Further Notes。

产物：发布到已配置 Issue Tracker 的规格，并标记 ready-for-agent。

边界：它明确禁止重新访谈。需求还没讨论清楚时应先用 grill-with-docs。规格也不应塞入易过期的具体文件路径和实现代码；原型中真正表达决策的状态机或类型片段是例外。

7. to-tickets

类型：用户触发型。

解决的问题：把规格或计划拆成单个新上下文可以完成的 tracer-bullet tickets。

拆分原则：每个 ticket 必须穿过必要的 schema、API、UI 和测试层，完成后能独立演示或验证。不能横向拆成“先写数据库”“再写接口”“最后写页面”。

依赖模型：每个 ticket 声明 blocking edges。没有 blocker 的任务构成当前 frontier，可以立即执行。

特殊情况：全仓库重命名等 wide refactor 不能硬切垂直片，应使用 expand–migrate–contract：先兼容新旧形式，分批迁移调用方，最后删除旧形式。

产物：本地 .scratch/<feature>/issues/ 下的一票一文件，或真实 Tracker 上带原生阻塞关系的 Issues。

边界：发布前必须向用户展示粒度和依赖关系并取得批准；不关闭或修改父 Issue。

8. implement

类型：用户触发型。

解决的问题：实施 spec 或 tickets，并把底层质量纪律串起来。

执行协议：

读取任务
→ 在预先确认的 seams 使用 tdd
→ 经常运行类型检查和单文件测试
→ 结束时运行完整测试集
→ code-review
→ 提交当前分支

设计亮点：SKILL.md 只有十几行，是刻意保持薄的 orchestrator。测试规则由 tdd 管，评审规则由 code-review 管，避免在多个流程复制同一套纪律。

边界：它最终会提交代码，因此必须由用户主动启动。没有明确规格时不应把它当需求探索工具。

9. wayfinder

类型：用户触发型。

解决的问题：处理一个 Agent 会话装不下、连完整路线都暂时看不清的大型工作。

核心模型：建立一个带 wayfinder:map 标签的主 Issue，子 Issue 不是实施票，而是“决策票”。地图包含 Destination、Notes、Decisions so far、Not yet specified 和 Out of scope。

Fog of war：已经能精确提出的问题创建 ticket；还无法准确表达的疑问留在 Not yet specified。解决当前 frontier 的决策后，新的问题才从迷雾中升级成 ticket。

Ticket 类型：Research、Prototype、Grilling、Task。前三者分别解决知识、可视化验证和人的决策；Task 只做为后续决策解锁所必需的准备工作。

边界：默认只规划、不实施。每个会话最多解决一个决策票，研究票除外。地图走通后通常进入 to-spec → to-tickets → implement，而不是直接开工。

10. prototype

类型：模型触发型。

解决的问题：有些设计问题靠讨论无法回答，需要一个便宜、可运行、可观察的东西。

两个分支：

• Logic/state：生成一个单 HTML，可通过按钮和引导步骤推动状态机；
• UI：在单一路由中生成多个差异足够大的方案，通过 URL 参数或浮动切换器查看。

规则：明确标成 prototype；一条命令即可运行；默认内存状态；不写测试和生产级错误处理；始终展示完整相关状态。

产物：用于回答一个明确问题的抛弃式代码。验证后的结论进入真实实现，原型保留在 prototype/<name> 分支作为一手证据，主分支不保留原型代码。

边界：throwaway 不是随便写，而是禁止投入与问题无关的工程成本。

11. diagnosing-bugs

类型：模型触发型。

解决的问题：疑难 Bug、间歇性故障和性能回归，防止模型看几眼代码就给出第一条“合理解释”。

六个阶段：

1. 建立一条已经实际运行过、能捕获用户精确症状的快速反馈命令；
2. 复现并逐项删减，得到最小复现；
3. 提出 3～5 个可证伪且排序的假设；
4. 一次改变一个变量，用 debugger、定向日志或 profiler 验证；
5. 在正确 seam 先写回归测试，再修复并重跑原始场景；
6. 删除 [DEBUG-...] 插桩和临时原型，记录真正根因。

关键门禁：没有一条已跑过、red-capable、确定性、足够快、Agent 可独立执行的命令，就不能进入假设阶段。

边界：如果没有正确 seam 能覆盖真实 Bug 模式，应把“架构无法锁定回归”作为发现，交给 improve-codebase-architecture，而不是补一个虚假的浅层测试。

12. research

类型：模型触发型。

解决的问题：把文档、规范、源码和第三方 API 的阅读工作交给后台 Agent，同时主会话继续推进。

执行过程：只依赖官方文档、规范、源码和第一方 API 等一手资料；每个关键结论追溯到来源；写成单一带引用 Markdown；遵循项目已有的研究文档位置。

产物：仓库中的研究 Markdown。

边界：研究提供事实，不替代产品决策。结果通常带回 grill-with-docs 继续讨论。

13. tdd

类型：模型触发型。

解决的问题：让 Agent 写出能长期保留的行为测试，而不是只追求测试数量。

核心规则：测试公开 interface 上的行为；写测试前先与用户确认 seam；一次只做一个 seam、一个失败测试、一个最小实现。

反模式：

• Implementation-coupled：测私有方法、内部调用或绕过公开接口；
• Tautological：用和实现相同的算法算期望值；
• Horizontal slicing：一次写完所有测试，再一次实现所有代码。

特殊观点：当前版本把重构移出 red-green 循环，放到 review 阶段，以减少 Agent 在测试转绿后顺手扩大修改。

边界：seam 本身都不清楚时先调用 codebase-design；不能为了 TDD 给每个内部函数都造一个测试入口。

14. domain-modeling

类型：模型触发型。

解决的问题：让用户、代码和 Agent 使用同一套领域语言。

执行过程：发现术语与 glossary 冲突时立即指出；把“account”这类含糊词拆成更精确的概念；用边界场景压力测试关系；检查用户描述与代码是否一致；决策一落地就立即更新文档。

产物：CONTEXT.md 只保存领域 glossary，不保存实现细节；真正难以逆转、缺少背景会令人困惑且存在真实取舍的决策才写 ADR。

边界：只读取 CONTEXT.md 不算 domain-modeling；只有主动修改领域模型时才触发。

15. codebase-design

类型：模型触发型。

解决的问题：为架构设计提供一套稳定的“深模块”词汇和判断方法。

核心词汇：Module、Interface、Implementation、Depth、Seam、Adapter、Leverage、Locality。它刻意避免用含义容易漂移的 component、service、API、boundary 替代这些词。

核心判断：一个深模块用较小 interface 提供较多行为；interface 同时也是测试面；好的 seam 提高 locality；只有一个 adapter 时 seam 可能只是猜想，存在两个实现时 seam 才得到真实证明。

常用方法：deletion test 判断删除一个抽象后复杂度会集中还是只会转移；design it twice 用不同方案比较 interface，而不是接受第一个设计。

边界：它是词汇和设计纪律，不是独立的大型重构流程。具体扫描由 improve-codebase-architecture 负责。

16. code-review

类型：模型触发型。

解决的问题：分别判断“代码写得是否符合项目规则”和“代码是否实现了正确需求”。

执行过程：固定 commit、branch、tag 或 merge-base；使用 git diff <fixed-point>...HEAD；从提交信息、用户参数或规格目录定位 spec；收集项目编码规范；分别启动 Standards 与 Spec 两个子 Agent。

Standards 轴：检查项目规则，并补充 Fowler smell baseline，如 Mysterious Name、Feature Envy、Shotgun Surgery、Speculative Generality。项目明确规则优先，smell 只能作为判断提示。

Spec 轴：寻找漏实现、部分实现、错误实现和 scope creep。

产物：两个并列报告，不合并、不跨轴重排严重度。

边界：没有固定基准就先询问；diff 为空或 ref 不存在要在启动子 Agent 前失败；没有 spec 时明确跳过 Spec 轴。

17. resolving-merge-conflicts

类型：模型触发型。

解决的问题：根据改动意图解决正在进行的 merge/rebase，而不是机械选择 ours 或 theirs。

执行过程：检查 Git 状态和冲突文件；从 commit、PR、Issue 找到两侧一手来源；逐 hunk 尽量保留双方意图；冲突不可兼容时选择符合本次合并目标的一侧并记录取舍；运行 typecheck、tests、format；stage 并继续完成 merge/rebase。

边界：永远不执行 --abort，也不趁解决冲突发明新行为。

18. wizard

类型：模型触发型。

解决的问题：把 Agent 无法代替人完成的浏览器配置、凭证获取、迁移或切换步骤做成交互式 Bash 向导。

执行过程：先从 .env*、README、compose 和 CI 配置识别所有值；与用户确认阶段及每个值的来源、落点和敏感性；为每个阶段写精确页面路径；基于固定 template.sh 只编写 stages；使用隐藏输入、幂等 env upsert、GitHub secrets/vars 和不可逆操作确认。

产物：临时或可提交的 Bash wizard。

边界：Agent 能做的事不应甩给人；只静态验证和运行 bash -n/shellcheck，不能自己把需要人工交互的向导跑到底。

---

二、正式生产力 Skills

19. grill-me

类型：用户触发型。

作用：无状态地启动 grilling。适合写作计划、产品想法、非仓库设计等没有项目文档可落地的场景。

产物：对话中达成的共同理解，不写本地 glossary 或 ADR。

边界：在真实仓库中优先用 grill-with-docs，因为后者能保存稳定知识。

20. grilling

类型：模型触发型，是多个访谈流程的底层原语。

核心机制：把决策建模为 design tree。每轮只询问前置条件已经确定的全部 frontier 节点；每个问题编号并给推荐答案；用户回答后重新计算 frontier。

职责划分：环境和代码中的事实由 Agent 自己调查；产品和设计取舍由用户决定。不能把可查询事实推给用户，也不能替用户回答决策。

退出条件：frontier 为空，并由用户确认双方理解一致。确认前不能开始实施。

边界：问题依赖本轮尚未回答的另一个问题时，必须推迟到下一轮。

21. handoff

类型：用户触发型。

解决的问题：把当前会话交给新的 Agent、目录、工具或同事。

执行过程：生成聚焦下一会话目标的摘要，列出建议调用的 Skills；已经存在于 spec、ADR、Issue、commit 或 diff 的内容只放路径或 URL，不重复复制；清理密钥、密码和个人信息。

产物：操作系统临时目录中的 Markdown handoff。

边界：它购买的是“可移植性”，不是普通上下文压缩；同一目录继续工作时通常优先 continue 或 compact。

22. teach

类型：用户触发型。

解决的问题：把一次问答升级为可跨多个会话持续推进的学习系统。

工作区：MISSION.md 保存学习原因；RESOURCES.md 保存高可信资料；learning-records/ 记录非显然收获；lessons/ 保存短小 HTML 课程；reference/ 保存长期查阅资料；assets/ 保存复用样式和交互组件；NOTES.md 保存偏好。

教学方法：课程必须服务 mission，并落在最近发展区；知识获取降低不必要难度，技能训练使用检索练习、间隔和交错增加“有益困难”；课程短小但必须有可操作成果和即时反馈环。

边界：mission 不清楚时先询问学习目的。不能只靠模型记忆，应建立高可信资源列表。

23. to-questionnaire

类型：用户触发型。

解决的问题：真正的答案不在用户或代码库里，而在某位业务专家、客户或同事脑中。

执行过程：只采访“怎么发送”，不采访用户答不出的主题。先确认收件人的角色和知识，再确认需要拿回哪些事实或决策，最后生成按重要程度排序的 discovery questionnaire。

产物：当前目录中的 to-questionnaire-<slug>.md，包含目的、发件人/收件人、上下文、答题说明、分主题问题和答案占位。

边界：每个问题只问一个概念；允许“不知道”和部分回答；可误解的问题才补“为什么重要”。

24. wait-what

类型：用户触发型。

解决的问题：上一条解释没有让用户听懂时，立即重讲，而不是继续在错误理解上推进。

执行要求：补充缺失上下文；使用 ASD-STE100 Simplified Technical English；如果存在 CONTEXT.md，使用项目统一领域语言。

边界：它只重讲刚才的信息，不启动新的研究或实施流程。

25. writing-for-agents

类型：模型触发型。

解决的问题：编写 Skill、AGENTS.md、CLAUDE.md 或被它们引用的文档时，减少触发不稳定和步骤遗漏。

核心概念：context pointer 的文字同时决定“这是什么”和“什么条件下读取”；弱指针会让再完整的参考资料也无法稳定触发。区分 context load 与 human cognitive load，避免把所有规则常驻上下文。

信息层级：顺序步骤放主文件；只在部分分支需要的参考内容通过明确指针渐进披露到旁文件。不要把关键步骤藏太深，也不要让大量参考资料淹没执行顺序。

边界：Skill 的写作目标不是每次产出同样文本，而是让模型每次采取同样、可检查的过程。

---

三、实验中的 Skills

这些 Skill 不进入正式插件和顶层 README，可能随时改变或删除。可单独安装：

npx skills@latest add mattpocock/skills --skill=<name>

26. claude-handoff

handoff 的 Claude Code 后台执行版本。它不把摘要保存成文件，而是运行：

claude --bg --name "<任务名>" "<handoff summary>"

新 Agent 在当前目录立即接手，用户通过 claude agents 管理。仍需引用已有资产、列建议 Skills、清除敏感信息。

27. loop-me

把生活或工作中的重复活动识别为 loop，再通过多轮 grilling 写成 workflows/*.md。它关注 trigger、human checkpoint、push right 和 decision-ready brief，但不强制所有 workflow 都使用 AI、定时器或人工检查。

28. setup-ts-deep-modules

为 TypeScript 仓库安装 dependency-cruiser，把 package 根文件定义为公开 entry points，把所有子目录视为私有实现。它试图用静态依赖规则强制“外部只能经过公开接口，测试也从 seam 进入”的深模块结构。

29. writing-fragments

写作 explore 阶段：通过 grilling 挖出可能进入文章的句子、观点、场景、类比和 leading word，持续追加到单一 Markdown。它禁止提前列大纲或确定结构，fragment 之间仅用分隔线隔开。

30. writing-shape

写作 exploit 阶段：读取固定的原始素材，先确定读者已有知识，再给出多个开头，让用户选择后逐段生长文章。每一段只能依赖已经 grounded 的概念，缺少必要素材时明确指出，而不是临场编造。

31. writing-beats

同属 exploit，但用 choose-your-own-adventure 的 beat 模型组织文章。每轮给 2～3 个下一节方向，用户选定后只写当前 beat，再根据已经建立的概念决定接下来能走向哪里。

---

四、杂项 Skills

这些是作者保留但很少使用的工具，不进入正式插件。

32. git-guardrails-claude-code

为 Claude Code 安装 PreToolUse Hook，阻止 git push、reset --hard、clean -f、branch -D、checkout . 和 restore .。支持项目级或全局配置，安装时要合并既有 settings，不能覆盖其他 Hook。

33. migrate-to-shoehorn

只用于测试代码，把 TypeScript 的 as Type 迁移为 @total-typescript/shoehorn：部分但仍类型检查的数据用 fromPartial()，故意错误的数据用 fromAny()，完整对象用 fromExact()。严禁用于生产代码。

34. scaffold-exercises

为特定课程仓库创建 XX-section/XX.YY-exercise/{problem,solution,explainer} 结构，补齐非空 readme.md，运行专用 linter，并用 git mv 保留重命名历史。它高度依赖作者自己的课程仓库约定，不是通用脚手架。

35. setup-pre-commit

检测 npm/pnpm/yarn/bun，为仓库安装 Husky、lint-staged 和 Prettier，按项目现有 scripts 决定是否在 pre-commit 中运行 typecheck/test。已有 Prettier 配置时不覆盖，最终通过一次真实提交验证 Hook。

---

五、怎么实际选择

第一次在仓库使用              → setup-matt-pocock-skills
普通新功能                    → grill-with-docs → implement
跨多个会话的新功能            → grill-with-docs → to-spec → to-tickets → implement
设计问题无法靠讨论回答        → prototype
很大且路线不清楚              → wayfinder → to-spec → to-tickets
外部 Issue/PR 需要整理        → triage
疑难 Bug                     → diagnosing-bugs
只想测试驱动完成明确行为       → tdd
检查分支是否写对、做对         → code-review
寻找架构改进点                → improve-codebase-architecture
解决正在进行的 merge/rebase   → resolving-merge-conflicts
必须让人操作第三方后台         → wizard
非仓库想法需要问清楚           → grill-me
把上下文交给新会话或同事       → handoff
不知道该选哪个                → ask-matt

最实用的入门顺序不是一次学完 35 个，而是：

1. setup-matt-pocock-skills；
2. grill-with-docs；
3. tdd；
4. implement；
5. code-review；
6. 工作真的跨会话时再引入 to-spec、to-tickets 和 handoff；
7. 只有大型模糊项目才使用 wayfinder。