Matt Pocock 的 AI Skills for Real Engineers 把需求澄清、领域建模、规格整理、任务拆分、测试驱动实现和代码审查分别做成可组合的 Skill。官方指南把它们按使用时机分组，其中「The Main Flow」是从想法走向交付的主干。
这种设计处理的是 AI 编程中三个反复出现的问题：意图没有说清、上下文越积越长、实现结果缺少独立验证。模型仍然负责推理和生成代码，但讨论结果会写入文档，复杂任务会切成可验证的纵向切片，审查也会放进独立上下文。
以下命令、目录和流程以 2026 年 8 月 6 日发布的 mattpocock/skills v1.2.3 为准；后续版本可能调整名称、安装方式和默认动作。
先区分技能库与安装器
v1.2.3 提供两种安装入口。Claude Code 可以安装托管的只读 Plugin，Codex 和其他 Agent 则通过 Vercel Labs 维护的 skills CLI 选择需要的 Skill。两种方式不要同时安装，否则同一项 Skill 会出现两份。
Claude Code Plugin 的安装命令是：
claude plugins install mattpocock-skillsCodex 和其他 Agent 使用：
npx skills@latest add mattpocock/skills交互式安装会选择具体 Skill、目标 Agent、安装范围和连接方式。使用 CLI 时，应确保选中 setup-matt-pocock-skills。当前安装器的关键选项如下：
| 选择 | 适用情况 | 结果 |
| Project，默认 | 团队项目 | Skill 保存在项目范围，可随仓库共享和审查 |
Global，-g | 个人跨项目使用 | Skill 放在用户目录，对多个项目可见 |
| Symlink，推荐 | 本机文件系统支持符号链接 | 多个 Agent 指向同一份 Skill，更新位置集中 |
Copy，--copy | 环境不支持符号链接 | 每个 Agent 持有独立副本，需要分别维护 |
团队优先选择 Project，因为 Skill 本身包含流程、术语和质量门槛，属于项目开发契约的一部分。项目级文件可以随仓库共享，成员和 Agent 能使用同一套配置，也能通过 Git 审查修改。Global 更适合个人偏好或多个仓库都需要的通用能力。
Main Flow 之前先完成 Setup
setup-matt-pocock-skills 属于「Getting Started」，不是「The Main Flow」的一环。安装完成后，需要在每个目标仓库调用一次：
/setup-matt-pocock-skills这个 Skill 不修改其他 SKILL.md，而是把仓库差异写进 docs/agents/。它主要确定三件事：
Issue tracker 在哪里。GitHub、GitLab 和本地 Markdown 有内置模板；Jira、Linear 等系统通过「Other」记录自定义操作流程。
Triage labels 如何映射。只有安装了
triage时才会生成对应配置，默认角色包括needs-triage、needs-info、ready-for-agent、ready-for-human和wontfix。Domain docs 如何组织。绝大多数仓库使用根目录
CONTEXT.md与docs/adr/；检测到大型 monorepo 信号后，才会提供CONTEXT-MAP.md与多上下文布局。
Setup 还会在已有的 CLAUDE.md 或 AGENTS.md 中加入 ## Agent skills 指针。当前选择规则是优先修改已存在的 CLAUDE.md，其次是 AGENTS.md；两者都不存在时再询问创建哪一个。
这一步为每个仓库建立独立契约。Issue 存放位置、领域术语和架构决策都与代码库绑定，应当进入版本控制。完成 Setup 后，主流程中的 to-spec、to-tickets 与 implement 才不需要猜测 tracker 和领域文档的位置。
两类 Skill 控制上下文开销
当前仓库按调用权限区分两类 Skill：
| 类型 | 如何触发 | 负责什么 |
| User-invoked | 开发者显式输入 /skill-name | 编排流程、提出分支问题、决定下一步调用什么 |
| Model-invoked | 开发者调用，或 Agent 根据任务自动选择 | 提供 TDD、研究、领域建模和代码设计等可复用方法 |
User-invoked Skill 通常带有 disable-model-invocation: true，Agent 不会自行触发。它们的描述只需支持发现和路由，完整流程等到显式调用后才进入上下文，从而减少常驻指令对上下文窗口的占用。
主流程如何运行
AIHero 将「The Main Flow」定义为按顺序衔接的 idea → ship 主干：
grill-with-docs → to-spec → to-tickets → implement → code-reviewask-matt 同样属于「Getting Started」。它是覆盖整个技能库的手写路由器，不是主流程中的第六步：不知道下一步调用哪个 Skill 时，用它取得建议；已经确定目标 Skill 时可以直接调用。
完整流程展示的是多会话路径。已经决定的工作能在一个新的 context window 中完成时，可以从访谈直接进入 implement；需要跨会话时，再用 Spec 保存决定、用 Tickets 组织执行。
1. grill-with-docs：先形成共享语言
grill-with-docs 是主流程的起点，适合在仓库内处理能够在一个会话中澄清的计划。它调用 grilling 进行分轮访谈，同时使用 domain-modeling 维护领域文档。Agent 不只提问，还会扫描代码库、核对已有术语，并把已经确认的信息写入：
CONTEXT.md：定义领域词汇，以及应避免的近义词；docs/adr/：记录重要架构决定、背景和后果；CONTEXT-MAP.md：仅在多上下文仓库中指向相关领域文档。
这三类结果并不等价。术语在确认时立即进入 CONTEXT.md；只有同时满足「难以逆转、脱离背景会令人意外、存在真实权衡」的决定才进入 ADR；其余决定只保留在当前会话中。因此，访谈结束后应直接把同一会话交给 to-spec，或者在工作足够小时直接调用 implement，不能把 glossary 当成完整规格。
深度访谈的价值在于提前暴露分支：角色是谁、行为边界在哪里、旧数据如何迁移、失败后如何恢复、哪些条件可以验收。实现前解决这些问题，成本通常只是一次讨论；代码生成后再发现理解不同，修改会扩散到接口、数据结构和测试。
访谈也不能替代验证。事实可以从代码、日志和文档中查证，产品取舍仍要由负责决定的人确认。CONTEXT.md 只记录稳定术语，不适合堆放完整聊天记录。
2. to-spec：把讨论压缩成终点定义
to-spec 只在工作需要跨越多个会话时体现价值。它把刚刚达成一致的会话整理成一张 Spec issue，不重新做需求访谈，也不验证或发明决定。它会先提出尽量少、尽量高层且优先复用现有边界的测试 seam，等待确认后再写正文。当前模板包括：
Problem Statement 与 Solution；
完整的 User Stories；
Implementation Decisions；
Testing Decisions；
Out of Scope 与 Further Notes。
它要求描述模块、接口、契约和测试决定，但默认不写具体文件路径或实现代码，因为这些细节在开发过程中最容易失效。Spec 描述的是完成后的外部行为和关键决定，为后续会话提供稳定终点。任何从未在上游讨论中确认、却由模型补入 Spec 的内容，都应视为缺陷。
这也是一次上下文压缩。数万 token 的讨论包含尝试、否定和重复解释，Spec 只保留已经确认的结论。压缩会丢失信息，因此应在同一会话中完成访谈、Spec 和 Tickets；如果会话接近 Smart Zone，再选择最近的阶段边界执行 /compact。
3. to-tickets：按可验证纵向切片拆分
to-tickets 可以读取 Spec、当前会话中的计划，或一份已经明确的方案，再把工作拆成可以单独验证的纵向切片。每个 Ticket 都是 tracer bullet，贯穿完成一种行为所需的层次。「先数据库、再 API、最后 UI」这类水平拆分不符合它的默认规则。例如，第一张 Ticket 可以只交付一种最小订单路径，但要同时包含必要的数据、接口、界面和测试。
在写入 tracker 前，它会先检查是否需要 prefactoring，再用编号列表展示拆分结果和依赖关系，等待开发者确认粒度、合并或拆分建议。每张 Ticket 都应能回答「完成后可以演示什么」，且答案必须是一项行为，而不是某个技术层。
每张 Ticket 还要声明 blocking edges。没有 blocker 的 Ticket 可以立即开始；有依赖的 Ticket 只有在前置工作完成后才进入可执行状态。本地 tracker 会把它们保存为 .scratch/<feature>/issues/<NN>-<slug>.md，真实 tracker 则尽量使用原生依赖关系。
Ticket 大小以「能否在一个新的上下文窗口中完成」为准，不用固定行数衡量。当前 ask-matt 把 Smart Zone 描述为先进模型仍能清晰推理的约 150k tokens 区间。这个数值属于工作流的经验阈值；模型、Agent 运行环境、工具输出和任务类型都会改变有效范围。
纵向切片提高了局部可验证性，也会增加规划和依赖管理成本。机械式的大范围重命名很难保持每个切片独立通过，to-tickets 对这类 Wide Refactor 使用 expand-contract：先兼容新旧形式，再分批迁移调用方，最后删除旧形式。
4. implement：一次只完成一张 Ticket
implement 消费已经决定的计划，不重新讨论方案。一次运行只处理一张 Ticket：先读取 Ticket 或 Spec，在预先确认的 seam 上调用 tdd，按 red-green slice 实现，过程中反复运行类型检查和单个测试，结束前再运行完整测试套件。它不会创建分支，也不会关闭 Ticket、勾选 acceptance criteria 或自动处理 review findings，最后会提交到当前分支。
这个自动提交行为需要提前纳入仓库规则。若团队要求人工批准 commit，应在 AGENTS.md 或 CLAUDE.md 中写明，不能假设所有 Skill 都采用相同的 Git 授权边界。多张 Ticket 可以分配到不同的新会话，但不能让多个会话共享同一 working tree、index 和 HEAD 后并发提交；需要并行时，应为每项工作准备独立 worktree 和分支。
5. code-review：分别检查 Standards 与 Spec
code-review 沿两个轴检查从固定 Git 基准点到 HEAD 的差异：
| 审查轴 | 判断依据 | 主要问题 |
| Standards | 仓库编码规范与 Fowler code smells 基线 | 实现是否清楚、局部、符合项目约定 |
| Spec | 原始 Issue 或 Spec | 需求是否遗漏、实现错误或出现范围外改动 |
两个审查轴由独立子 Agent 执行，最后并列汇总，各自报告最严重的问题，不合并成一个总分。独立上下文可以减少两个审查维度相互影响，也能防止「代码很整洁」掩盖「实现了错误需求」。
当前 implement 会在 commit 前调用 code-review，但 code-review 使用 <fixed-point>...HEAD，看不到 staged 或 working tree 中尚未提交的改动。更可靠的做法是在 commit 后，用新的会话给出明确 fixed point 再独立审查；修复 findings 后追加 commit 或 amend。即使审查没有发现问题，客观正确性仍需由测试、类型检查、真实运行结果和人工判断共同证明。
用文档保存跨会话状态
这套工作流把不同类型的状态放进不同载体：
| 载体 | 保存什么 | 回答的问题 |
CONTEXT.md | 稳定领域术语 | 项目中的词具体指什么 |
| ADR | 难以轻易逆转的架构决定 | 当时为什么这样选择 |
| Spec | 目标行为、范围和测试决定 | 最终要交付什么 |
| Tickets | 纵向切片与依赖关系 | 下一步可以执行什么 |
| 代码与测试 | 当前实现和可重复证据 | 系统现在实际做什么 |
这些文件共同承担跨会话状态，但它们的权威范围不同。使用某个 Skill 时，具体 SKILL.md 高于 ask-matt 的摘要；判断需求时，已批准 Spec 高于旧聊天片段；判断系统现状时，代码、测试和运行结果高于过期文档。
ask-matt 是流程路由，不是每项 Skill 的完整说明。只要某条建议会影响任务拆分、提交或发布，就应打开对应的 AIHero Skill 指南 和目标 SKILL.md 核对，路由摘要只用于定位下一步。
怎样按任务规模采用
这套流程可以逐步引入，不必一次安装全部 Skill。
对于一个会话内能完成的小功能，可采用：
setup（每个仓库一次）
→ grill-with-docs
→ implement
→ 在新会话中 code-review
→ verify对于跨多个会话的功能，可采用：
setup（每个仓库一次）
→ grill-with-docs
→ to-spec
→ to-tickets
→ 每张 Ticket 开新会话运行 implement
→ 更新 Ticket 状态
→ 独立 code-review 与集成验证对于还无法通过讨论回答的状态模型、业务逻辑或 UI 问题，先用 handoff → prototype → handoff 做一次可运行实验，再回到原流程。对于更庞大且方向仍不清楚的 Greenfield 项目或大型功能，当前仓库还提供 wayfinder，先用 Decision Tickets 消除关键未知项，再进入 to-spec。
第一次实践时，最好选择一项边界清楚、能够运行测试、又确实需要澄清需求的真实改动。完成后检查四件事：领域术语是否更统一，Spec 是否删掉了讨论噪声，每张 Ticket 是否能单独验收，双轴审查是否发现了不同类型的问题。只有这些结果成立，流程成本才有实际回报。
