AI 参与说明（Agent：Codex）：本文由 Codex 根据
mattpocock/skills官方仓库与本机安装快照协助整理和校验。资料核验于 2026-08-25，上游源码锁定为提交6654f6b。本文核对了 skill 名称、分类、调用策略与公开工作流，但未实际运行setup-matt-pocock-skills，也未用整套流程完成真实工程交付；具体行为仍应以所用 Agent Harness、仓库规则和锁定版本的SKILL.md为准。
先说结论#
Matt Pocock Skills 不是 TypeScript 语法、类型体操或框架 API 的知识包，而是一套可组合的 AI software engineering workflow。它把开发者与 Agent 的协作拆成若干小型 skill：先澄清需求和统一领域语言，再形成 specification、拆分可交付任务、用 Test-Driven Development（TDD）实现，最后按代码规范和原始需求两条轴线复核结果。
它也不是要求团队接受一整套封闭方法论的“全自动开发框架”。官方 README 强调小型、可修改、可组合和 model-agnostic；用户仍掌握工作流入口、项目规则与最终决策。更准确地说，这套 skills 是把传统软件工程纪律包装成 Agent 可以重复执行的工作单元，而不是用更多 prompt 掩盖工程反馈闭环。项目 README
它试图解决哪几类问题#
官方把常见失败归纳为四条主线：Agent 没理解需求、项目没有共享语言、生成的代码缺少可运行反馈，以及代码库在快速生成代码后加速退化。对应的处理方式分别是 grilling、CONTEXT.md 与 Architecture Decision Record（ADR）、TDD 与诊断循环，以及 deep module / clean seam 等代码设计纪律。项目 README
因此，它的价值不在于“多装了 37 条命令”，而在于建立一条可检查的证据链：
- 需求通过持续提问被明确，而不是靠 Agent 猜测。
- 关键术语、边界和决定进入
CONTEXT.md与 ADR，而不是只留在聊天历史中。 - 计划被切成有阻塞关系的 tracer-bullet tickets，而不是一份顺序很长的待办清单。
- 实现通过测试、运行结果和诊断 instrumentation 获得反馈。
- Review 同时追问“是否符合仓库标准”和“是否忠实实现原始 specification”。
本机为什么是 37 个 skills#
截至本次核验，本机新安装快照中的 37 个 skill 名称与锁定提交下全部 SKILL.md 一一对应。这个数字由四部分组成：稳定 Engineering 18 个、稳定 Productivity 7 个、In Progress 8 个、Misc 4 个。上游目录在安装后被展平，因此仅看本机同级目录，无法直接知道某项是否属于稳定核心。
稳定 Engineering：18 个#
这组覆盖从需求入口到代码交付的主要工程活动。Engineering 清单
- 对齐与编排：
ask-matt负责推荐适合的 skill；grill-with-docs在追问设计的同时维护领域文档；setup-matt-pocock-skills配置仓库级约定；wayfinder为跨多个 Agent session 的大型工作维护决策地图。 - 规划与交付：
to-spec把已有对话整理成 specification；to-tickets拆成声明阻塞边的 tracer-bullet tickets；implement按 specification 或 tickets 实现；triage让 Issues 在明确的 triage role 状态机中流转。 - 反馈与设计：
prototype做可丢弃的状态、逻辑或 UI 验证；diagnosing-bugs建立可复现、最小化、假设、instrumentation、修复和 regression test 的诊断循环；research要求后台 Agent 使用高可信一手来源；tdd以 red → green 的垂直切片推进，并把 refactor 放到 review 阶段。 - 代码库纪律：
domain-modeling维护领域词汇和 ADR；codebase-design提供 deep module、small interface 与 clean seam 的共同语言；improve-codebase-architecture扫描 deepening opportunities；code-review做 two-axis review；resolving-merge-conflicts按双方变更意图处理冲突；wizard为只能由人完成的凭据、控制台或 cutover 步骤生成交互式 Bash 向导。
稳定 Productivity：7 个#
这组不是专门写代码，而是处理协作、表达和知识传递。Productivity 清单
grill-me是用户显式启动的追问入口，grilling是其他 skill 可以复用的底层访谈纪律。handoff把当前对话压缩成可供另一 Agent 接手的文档。teach使用当前目录保存跨 session 的教学状态。to-questionnaire把本人无法独立决定的问题整理成发给决策者的问卷。wait-what在解释没有被理解时，利用项目词汇重新表达。writing-for-agents用于编写 skill、AGENTS.md、CLAUDE.md等给 Agent 阅读的文档。
In Progress：8 个#
claude-handoff、implement-spec、loop-me、retro、setup-ts-deep-modules、writing-beats、writing-fragments、writing-shape 都已被本机安装，但上游明确把它们标为 Beta：不进入稳定插件和顶层 README，没有完整文档页，未来可能修改或消失。其中 retro 在锁定提交中仍是设计 stub，不能当作已经成熟的 retrospective 工具。In Progress 说明
这组可以理解为三类实验：跨 Agent / 跨 session 交接与执行、TypeScript deep-module 约束，以及从 fragments 到 beats 再到 article shape 的写作流程。它们适合小范围试验，不应仅因“已经安装”就进入团队默认流程。
Misc：4 个#
git-guardrails-claude-code、migrate-to-shoehorn、scaffold-exercises、setup-pre-commit 是作者保留的低频专项工具。它们分别面向 Claude Code 的危险 Git 命令拦截、测试数据从 as assertion 迁移到 @total-typescript/shoehorn、课程练习目录脚手架，以及 Husky / lint-staged / Prettier / type check / test 的 pre-commit 配置。上游将 Misc 定义为“不常使用、也不在插件中推广”的工具，不应把它们误解为核心工作流的四个必选步骤。Misc 说明
User-invoked 与 Model-invoked#
这套仓库没有再用“command 与 skill”区分层级；每个 SKILL.md 都是 skill，唯一的分类轴是谁能够触发它。Invocation 规则
- User-invoked：只能由用户显式输入或从 UI 选择。Claude Code 通过
disable-model-invocation: true限制，Codex 通过agents/openai.yaml中的policy.allow_implicit_invocation: false表达同一策略。这类 skill 通常是需要人决定何时启动的编排入口。 - Model-invoked：用户可以显式调用，模型也可以在任务语义匹配时主动选择。它们通常承载可复用的诊断、设计、测试或写作纪律。
本机 37 项快照中，22 项是 User-invoked，15 项是 Model-invoked。组成方式是：稳定 25 项中有 14 项 User-invoked、11 项 Model-invoked；8 项 In Progress 当前均为 User-invoked；4 项 Misc 当前均为 Model-invoked。
这里的“Model-invoked”只是允许自动选择，不等于每次相关任务都一定触发。实际是否触发仍取决于 Agent Harness 是否加载该 skill、描述能否与当前意图匹配、项目级规则是否允许，以及更高优先级的用户指令。反过来，User-invoked 也不是“未安装”，只是模型不能擅自把它当成下一步。
从需求澄清到交付的主线#
下面的纵向流程是根据稳定 skills 的职责归纳出的实用主线，不是强制每个任务都完整走一遍。小修改可以跳过不需要的阶段；设计风险越高、参与者越多，保留 specification 与 tickets 的价值越大。
flowchart TD
setup["setup-matt-pocock-skills<br/>配置仓库约定"] --> grill["grill-with-docs<br/>澄清需求、更新 CONTEXT 与 ADR"]
grill --> decision{"是否有高风险设计假设？"}
decision -->|有| prototype["prototype<br/>制作可丢弃验证"]
decision -->|没有| spec["to-spec<br/>整理 specification"]
prototype --> spec
spec --> tickets["to-tickets<br/>拆 tracer-bullet tickets 与 blocking edges"]
tickets --> implement["implement<br/>按任务图推进"]
implement --> tdd["tdd<br/>red → green 垂直切片"]
tdd --> review["code-review<br/>refactor + Standards + Spec"]
review --> delivery["提交、交付或继续修正"]1. setup-matt-pocock-skills：安装之后的仓库配置#
安装只让 Agent 能读取 skills，并没有告诉它项目把 Issues 放在哪里、使用哪些 triage labels、CONTEXT.md 与 ADR 应放在哪里。setup-matt-pocock-skills 会先检查现有 Git remote、AGENTS.md / CLAUDE.md、monorepo 信号和已有文档，再让用户确认 Issue tracker 与领域文档布局。它是 prompt-driven skill，不是可盲目重复执行的确定性脚本。Setup skill
2. grill-with-docs：把模糊认识变成共享语言#
这一阶段不是让 Agent 一次生成更多内容，而是持续追问仍有多个答案的设计分支，并把稳定术语写入 CONTEXT.md、把难以逆转的决定写入 ADR。它减少后续 session 重新猜测项目术语的成本，也让代码中的 module、function 和文件命名有共同依据。Domain modeling
3. prototype：只在需要回答设计问题时插入#
prototype 的产物是 throwaway prototype，不是生产实现。状态与逻辑问题可以用单个可分享 HTML 验证，UI 问题可以并列多个差异足够大的方案。其价值是用低成本反馈淘汰错误假设；若需求和技术路径已经清楚，就不必为了流程完整而强行增加这一阶段。Prototype skill
4. to-spec 与 to-tickets：从共识到可抓取工作#
to-spec 不重新访谈，而是综合当前已经讨论的内容并发布到配置好的 Issue tracker。to-tickets 再把 specification 拆成可以独立抓取的 tracer-bullet tickets，每项声明 blocking edges。这里的目标不是把组件横向切成“先做全部数据库、再做全部 API、最后做 UI”，而是形成能尽早跑通反馈的垂直切片。Engineering 清单
5. implement：把 TDD 与 two-axis review 纳入交付#
implement 以 specification 或 tickets 为输入，在预先约定的 seam 上调用 tdd，并在提交前调用 code-review。当前 tdd/SKILL.md 要求每轮只做一个 red → green 垂直切片，refactor 留到 review 阶段；这比顶层 README 的概括更精确。code-review 将审查拆成两条相互独立的轴：Standards 检查仓库已有规则与 code smell baseline，Spec 检查实现是否忠实满足来源 Issue / specification；两者由并行 sub-agents 执行，避免一个审查视角污染另一个。TDD skill Implement skill Code review skill
三条常见 on-ramp#
并不是每项工作都从 setup 后的新需求访谈开始。稳定 Engineering skills 还提供三条常见入口：
- 已经有 Issue 队列：从
triage进入，验证、分类、补充信息并形成 agent-ready brief；它依赖 setup 中记录的 triage label vocabulary。 - 已经出现 bug 或 performance regression：从
diagnosing-bugs进入。先建立会在该 bug 上变红的反馈闭环，再最小化、提出假设、增加 instrumentation、修复并补 regression test，而不是直接修改第一个看起来可疑的位置。Diagnosing bugs - 工作量明显超过单个 Agent session：从
wayfinder进入，把未知点做成 decision tickets，按依赖逐个解决，直到执行路径清晰；它用于消除重大决策不确定性，不是另一种普通 task list。Wayfinder skill
domain-modeling 与 codebase-design 则贯穿这些入口。前者维护“这个业务中的词究竟是什么意思”，后者维护“行为应藏在多深的 module 后、interface 应多小、测试应通过哪条 seam 观察”。它们提供共同词汇，不负责替用户选择产品目标。Codebase design
安装不等于完成 repo setup#
通过 npx skills@latest add mattpocock/skills 安装的是普通、可编辑的文件副本。它不会在上游更新时自动改变；需要主动审阅并执行 npx skills update。这与 Claude Code 的 managed、read-only plugin 是两种分发哲学，二者同时安装还会造成重复 skill。锁定提交时，原生 Codex plugin 仍在 roadmap。安装说明
更重要的是，安装与仓库配置是两个阶段：
- 安装解决“Agent 能否看到这些 skill 文件”。
- repo setup 解决“这些 skill 在本仓库应读取和写入什么”。
在普通代码仓库使用前，应先审阅 setup 准备修改的 AGENTS.md 或 CLAUDE.md，确认 Issue tracker、triage labels、CONTEXT.md / ADR layout，以及它计划创建的 docs/agents/*.md。如果团队已经有同类约定，应适配现有结构，不能让通用 skill 覆盖项目规则。
Blog 兼容性警告#
不要在本 Blog 直接运行
setup-matt-pocock-skills。本项目已有公开内容目录docs/Agents/，而 setup 的默认配置文件位置是docs/agents/。在本机所使用的 macOS 大小写不敏感文件系统上，这两个路径会发生冲突；setup 计划写入的 Issue tracker、triage labels 与 domain 配置可能进入现有公开内容目录，并被 Hugo 当作站点内容发布。
风险不只是多出几个文件。该 skill 还会选择并修改 AGENTS.md 或 CLAUDE.md，记录 Issue tracker 与领域文档约定。在这个 Blog 中，目录创建、公开内容、Hugo contentDir、front matter 和 Agent 规则已经有更具体的项目约束；项目规则优先于通用 skill。即使只是想体验流程，也不应在 Blog 上直接跑 setup。
若要在普通代码仓库采用这套 skills，至少先审阅并确认以下变更面：
- 它准备修改
AGENTS.md还是CLAUDE.md，是否与既有 steering rules 冲突。 - Issue tracker 是 GitHub、GitLab、local Markdown，还是团队已有的其他系统。
- 五种 triage roles 如何映射到既有 labels，避免创建同义重复标签。
CONTEXT.md与 ADR 使用 single-context 还是 multi-context layout。docs/agents/是否会进入公开文档、制品、搜索索引或部署包。
适合与不适合的场景#
适合：
- 团队希望保留人工决策权，又想让 Agent 重复执行 specification、TDD、诊断与 review 纪律。
- 中大型变更经常跨 session、跨开发者或跨 Agent，需要共享领域语言和可追溯决定。
- 仓库已有自动测试、静态检查、Issue tracker 和代码规范，能给 Agent 快速、真实的反馈。
- 团队愿意按项目实际情况修改 skill，而不是把上游文本当作不可更改的框架。
不太适合：
- 一次性的小改动没有设计分支，也不值得建立 specification 与 tickets。
- 期待“装完即可无人监督完成整个产品”，不愿参与 grilling、review 和关键决策。
- 仓库没有可运行反馈，团队也不准备补测试、类型检查或验证方式；此时 TDD 与 diagnosis 只剩形式。
- 内容仓库或公开文档站的目录与 setup 默认路径冲突，却没有先做发布边界审查。
- 把 In Progress 或 Misc 全部设成团队默认，只因为安装器已经复制了文件。
建议先从哪几个开始#
不要一开始同时改变 37 种工作方式。普通代码仓库可以按下面顺序试用：
- 先阅读
setup-matt-pocock-skills的预期修改；确认路径和项目规则后，再完成一次 repo setup。Blog 是前述例外，不应直接执行。 - 新功能先试
grill-with-docs，观察它是否真正减少术语歧义和遗漏的设计分支。 - bug 使用
diagnosing-bugs，新实现使用tdd，把可运行反馈放到 prompt 之前。 - 在一个中等规模改动上试
code-review，比较 Standards 与 Spec 两条轴是否发现了不同问题。 - 只有当团队已经认可前述纪律，再引入
to-spec、to-tickets和implement的完整交付链。
如果不知道从哪个入口开始，显式调用 ask-matt；如果只是要重新解释一段没有听懂的说明，使用 wait-what。Beta 写作流程、implement-spec 和 retro 等 In Progress skills 可以最后再评估。
关联阅读#
- Pi Coding Agent 入门与社区玩法：区分 Agent Harness、Skills、Prompt Templates、Extensions 与 Packages，便于理解这些 skill 文件由谁加载和执行。
- 技术方案研究 Skill：从问题建模到路线比较与决策：一个更聚焦研究与技术选型的单项 Skill 实例。