mattpocock/skills 介绍

来源：github.com/mattpocock/skills，由 TypeScript 教育者/开发者 Matt Pocock 创建。

安装时间：2026-07-17，一次性批量安装 41 个 Skill，安装入口是 setup-matt-pocock-skills。

核心理念

这套 Skills 围绕工程工作流设计，不是零散的工具集，而是一套互相协作的技能体系。核心思路是：

  1. 把模糊想法变成可执行计划：to-spec → to-tickets → triage
  2. 用盘问（grilling）驱动质量：grilling / grill-me / grill-with-docs 反复追问你的计划
  3. 用领域建模统一团队语言：domain-modeling + ubiquitous-language
  4. 每个 Skill 职责单一、可组合：比如 grill-with-docs = grilling + domain-modeling

工作流全景

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
               setup-matt-pocock-skills（一次性配置）
                      │
      ┌───────────────┼───────────────┐
      ▼               ▼               ▼
  ask-matt        to-spec         wayfinder
（路由器）      （对话→spec）    （大型任务地图）
      │               │
      ▼               ▼
 to-questionnaire  to-tickets
（决策→问卷）      （spec→ticket链）
      │               │
      ▼               ▼
    triage          implement
（ticket状态机）    （执行实现）
      │               │
      ▼               ▼
 code-review ←─── diagnosing-bugs
（双维度审查）     （诊断循环）
      │
      ▼
resolving-merge-conflicts
（解决合并冲突）

关键 Skill 详解

工作流引擎

  • ask-matt — 入口路由器，不知道用哪个 Skill 就先问它
  • to-spec — 把当前对话直接合成 Spec，无需额外面试
  • to-tickets — 把 Spec 拆成带依赖关系的 tracer-bullet tickets
  • triage — 管理 issue 状态机：分类→验证→盘问→写 agent-ready brief
  • wayfinder — 超大型任务的决策地图，超出单次会话容量时使用

盘问体系（grill 四件套）

  • grilling — 核心：对你的计划/决策/想法进行无情追问，用于压力测试
  • grill-me — 主动请求被盘问
  • grill-with-docs — 盘问的同时产出 ADR 和术语表（依赖 grilling + domain-modeling）
  • batch-grill-me — 批量版，每轮同时抛出所有前沿问题

设计与架构

  • codebase-design — 深度模块设计方法论，教你找接口边界、模块深化机会
  • domain-modeling — 构建领域模型，确定通用语言
  • improve-codebase-architecture — 扫描代码库→生成 HTML 可视化报告→盘问式深入
  • code-review — 双维度（Standards + Spec）并行审查，并排报告

质量保障

  • tdd — 测试驱动开发，红-绿-重构
  • diagnosing-bugs — 针对疑难 bug 和性能回归的诊断循环
  • research — 代理调研，结果输出为 Markdown 文件
  • prototype — 抛弃式原型验证设计和逻辑

协作与交接

  • handoff — 把当前对话压缩成交接文档
  • claude-handoff — 直接把对话交给后台 agent 立即接手
  • teach — 在工作空间内教授新技能

目录结构（按仓库路径）

目录 数量 状态 内容
skills/engineering/ 14 ✅ 正式 工程核心技能
skills/productivity/ 5 ✅ 正式 生产力工具
skills/in-progress/ 10 🚧 实验 开发中功能
skills/deprecated/ 4 ⚠️ 废弃 已不再维护
skills/personal/ 2 👤 个人 Matt 个人使用
skills/misc/ 4 🧩 杂项 零散工具

与其他来源的关系

  • 不依赖 Gstack：mattpocock/skills 和 Gstack 是两套独立体系，名称无冲突
  • 不依赖 Superpowers：Superpowers 是流程规范（计划/调试/审查的时机），mattpocock 是执行工具（怎么做具体的事）
  • 配置入口：使用前需先运行 setup-matt-pocock-skills，它会配置 issue tracker、triage 标签、领域文档布局

mattpocock/skills 使用指南

基于各 Skill 的 SKILL.md 完整文档整理，包含触发条件、执行步骤、输入输出和 Skill 间的调用关系。

前置条件：一次性配置

在使用任何工程 Skill 之前，必须先运行一次：

1
/setup-matt-pocock-skills

它会做三件事：

  1. 配置 Issue Tracker（GitHub / GitLab / 本地 markdown），写入 docs/agents/issue-tracker.md
  2. 配置 Triage 标签（needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix）
  3. 配置领域文档布局（单上下文 CONTEXT.md + docs/adr/，或 monorepo 多上下文）

后续所有 Skill 都会读取这些配置。

Skill 调用关系总图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
                 ┌─────────────────────────────────┐
                 │  共享基础设施（被多个 Skill 调用）  │
                 │  grilling · domain-modeling      │
                 │  codebase-design（词汇层）         │
                 └─────────────────────────────────┘
                                 ▲
     ┌───────────┬───────────────┼───────────────┬───────────┐
     │           │               │               │           │
grill-with-docs  triage      wayfinder    improve-       diagnosing
     │           │               │        architecture   -bugs
     ▼           ▼               ▼            │           │
   to-spec    to-tickets     implement        ▼           ▼
     │           │               │      codebase-design  (Phase6
     ▼           ▼               ▼                      handoff)
   (发布到     (发布到         tdd ──► code-review
   tracker)   tracker)          │
                                ▼
                           (红-绿-重构循环)

场景一：从想法到上线（主工作流）

这是最完整的路径，适合有明确需求的开发任务。

第 1 步：盘问 + 打磨想法

1
/grill-with-docs

做什么：对计划或设计进行无情追问，同时生成 ADR 和术语表。

实际发生了什么：

  • 调用 /grilling —— 沿决策树逐层追问，一次一个问题，每个问题给出推荐答案
  • 同步调用 /domain-modeling —— 当术语达成共识时，实时更新 CONTEXT.md；当做出难以逆转的决策时，创建 ADR

什么时候用：你有一个想法但还不够清晰，希望 AI 帮你压力测试并把关键决策记录下来。

替代方案：

  • /grill-me —— 同上但不产出文档（无状态版本）
  • /batch-grill-me —— 批量版，每轮同时抛出所有前沿问题，逐轮推进

第 2 步：合成 Spec

1
/to-spec

做什么：把当前对话中的讨论合成为一份正式 Spec，发布到 Issue Tracker。

不需要额外面试——它只合成已经讨论过的内容。

Spec 包含：问题陈述、解决方案、用户故事（长列表）、实现决策（模块/接口/架构/API 契约，不含文件路径和代码）、测试决策、Out of Scope。

发布时会自动打上 ready-for-agent 标签。

第 3 步：拆分为 Tickets

1
/to-tickets

做什么：把 Spec 拆成一条 tracer-bullet ticket 链，每条 ticket 是贯穿所有层的完整垂直切片。

关键规则：

  • 垂直切片，不是水平切片（每条 ticket 走通 schema→API→UI→test）
  • 每条 ticket 声明阻塞边（blocked by），形成依赖图
  • 每条 ticket 适合在一个上下文窗口内完成
  • Prefactoring（”先让改动容易做”）的 ticket 排最前面
  • 发布时按依赖顺序（blocker 优先）

第 4 步：逐个实现

1
/implement

做什么：执行 ticket 的实现。

实际步骤：

  1. 调用 /tdd 进行红-绿循环（先写失败测试，再写最少代码通过）
  2. 在预先约定的 seam 处写测试（不确认 seam 不写测试）
  3. 定期运行类型检查
  4. 全部完成后调用 /code-review 进行双维度审查
  5. 提交到当前分支

第 5 步：代码审查

1
/code-review

做什么：两个子 Agent 并行审查：

  • Standards 维度：代码是否遵循仓库编码规范？是否有 12 种 Fowler 代码坏味道？
  • Spec 维度：代码是否匹配原始 issue/PRD？逐条对照 Spec 行

两篇报告并排呈现，末尾一行总结。

场景二：排查 Bug

诊断循环

1
/diagnosing-bugs

六个阶段的诊断流程：

Phase 1：构建反馈回路（核心）

按优先级尝试建立可复现的信号：

  1. 在能触及 bug 的 seam 处写失败测试
  2. curl/HTTP 脚本打开发服务器
  3. CLI 调用的 fixture 输入，diff stdout
  4. 无头浏览器脚本
  5. 回放抓取的 trace
  6. 抛弃式 harness
  7. 属性/模糊测试循环
  8. git bisect run 二分定位
  9. 新旧版本对比
  10. 人工交互 bash 脚本（最后手段）

然后收紧回路：更快、信号更清晰、更确定。

不完成此阶段绝不进入假设阶段。

Phase 2：复现 + 最小化

  • 确认回路能复现用户报告的精确故障模式
  • 最小化：一次删一个元素，重跑回路，直到每个剩余元素都是必要的

Phase 3：提出假设

  • 生成 3-5 个排序的、可证伪的假设
  • 格式：”如果 X 是原因，那么改变 Y 会让 bug 消失 / 改变 Z 会让它更糟”
  • 展示排序列表给用户，等待确认后再测试

Phase 4：探测验证

  • 每次只改变一个变量
  • 偏好：debugger/REPL > 定向日志 > 绝不”全量日志然后 grep”
  • 调试日志统一加 [DEBUG-xxxx] 前缀便于清理

Phase 5：修复 + 回归测试

  • 先写回归测试再修（只有在存在正确 seam 时才写）
  • 把最小化复现转为失败测试，看它失败，应用修复，看它通过

Phase 6：清理 + 复盘

  • 移除所有 [DEBUG-...] 代码
  • 在 commit/PR 中陈述正确的假设
  • 问：什么本可以防止这个 bug？ 如果答案是架构改动 → 交给 /improve-codebase-architecture

场景三：改进架构

扫描深化机会

1
/improve-codebase-architecture

三步走：

Step 1：探索

  • 如果用户指定了方向（模块/子系统/痛点），就走那个方向
  • 否则回溯 git log --oneline 找热点（反复出现的文件/区域）
  • 读取 CONTEXT.md 和 ADR
  • 使用 Explore Agent 遍历代码库，记录摩擦点：
    • 理解一个概念需要在很多小模块间跳转？
    • 模块浅薄（接口几乎和实现一样复杂）？
    • 纯函数被提取出来只为可测试性，但真正的 bug 藏在调用方式里？
    • 紧耦合模块跨 seam 泄漏？
    • 哪些部分未测试或难测试？
  • 对可疑的浅薄模块应用删除测试（想象删除它，复杂度是消失还是扩散到 N 个调用者？）

Step 2：生成 HTML 可视化报告

  • 自包含 HTML，写入系统临时目录，自动打开
  • 每张候选卡片含：涉及文件、问题描述、解决方案、收益（locality + leverage + tests）、Before/After 图、推荐强度徽章（Strong / Worth exploring / Speculative）
  • 用 CONTEXT.md 的领域词汇和 codebase-design 的架构词汇
  • 末尾有 Top Recommendation

Step 3：盘问式深入

  • 用户选一个候选 → 运行 /grilling 走决策树
  • 同步运行 /domain-modeling 更新 CONTEXT.md 和 ADR
  • 想探索替代接口？运行 /codebase-design 的 design-it-twice 模式

词汇参考

1
/codebase-design

这不是一个流程，而是一个共享词汇表——定义”模块”、”接口”、”深度”、”seam”、”adapter”、”leverage”、”locality”等术语的精确含义。被 improve-codebase-architecture 等 Skill 消费。

核心原则：

  • 深度是接口的属性，不是实现的属性
  • 删除测试：想象删除模块。如果复杂度消失，它是透传；如果分散到 N 个调用者，它物有所值
  • 接口 = 测试面
  • 一个 adapter = 假想 seam；两个 adapter = 真实 seam

场景四：处理外部 Issue 和 PR

Triage 状态机

1
/triage

两种模式：

模式 A：查看待处理列表

  • 查询 Issue Tracker
  • 分三个桶展示：未标记、needs-triage、needs-info（按最早优先）
  • PR 也会纳入范围，标注 [PR] 或 [issue]

模式 B：处理具体 Issue/PR

  1. 收集上下文

    ：读完整 issue/PR（正文+评论+标签），对 PR 还要读 diff。做两项检查：

    • 冗余检查：按领域概念搜索是否已有实现 → 有则 wontfix（已实现）
    • 先前拒绝检查：读 .out-of-scope/*.md → 有相似则标出

  2. 推荐：给出分类 + 状态建议，附推理和代码库摘要

  3. 验证：对 bug 按步骤复现；对 PR 确认 diff 做了它声称的事 —— checkout 后跑测试

  4. 盘问（如需要）：运行 /grilling + /domain-modeling

  5. 应用结果

    ：

    • ready-for-agent：写 agent brief（按 AGENT-BRIEF.md 模板）
    • ready-for-human：同上结构但说明为什么不能委托给 agent
    • needs-info：写 triage 笔记（”已有结论” + “还需要你提供”）
    • wontfix：关闭并附原因。已实现→指出位置；拒绝的 bug→礼貌解释；拒绝的 enhancement→写入 .out-of-scope/

状态机规则：每个 triage 后的 issue 必须恰好持有一个分类标签（bug/enhancement）+ 一个状态标签（needs-triage/needs-info/ready-for-agent/ready-for-human/wontfix）。

场景五：超大型任务（绿野仙踪）

1
/wayfinder

核心概念：地图是一个标记为 wayfinder:map 的 issue，其子 issue 是决策 ticket（不是构建切片）。

Ticket 类型：

类型 说明 解决方式
Research 读文档/API 获取事实 /research 子 Agent，无人交互
Prototype 廉价的具体产物来反应 /prototype
Grilling 对话决策（默认） /grilling + /domain-modeling
Task 手动操作解锁决策（如注册服务） 人工或 Agent

流程：

绘制地图（新想法）

  1. 运行 /grilling + /domain-modeling 确定目的地
  2. 广度优先盘问，暴露开放决策和第一步
  3. 创建地图 issue → 创建子 issue → 连线阻塞边
  4. 对 research ticket 并行启动子 Agent
  5. 停——绘制是一个会话，不解决任何东西

穿越地图（已有地图）

  1. 加载地图 → 选下一个 frontier ticket → 认领（assign 给自己）
  2. 按类型解决（默认 /grilling + /domain-modeling）
  3. 记录结论：在 ticket 中回复结论、关闭 issue、追加到地图的 Decisions-so-far
  4. 添加新浮现的 ticket、从迷雾中毕业新决策

关键规则：每次会话最多解决一个 ticket（research ticket 除外）。

场景六：快速原型验证

1
/prototype

两种分支：

问题类型 分支 做法
“这个逻辑/状态模型对吗？” LOGIC.md 构建微型交互终端应用，推动状态机通过难以推理的情况
“这个 UI 应该长什么样？” UI.md 在单一路由上生成多个截然不同的 UI 变体，通过 URL search param 和浮动底栏切换

原则：

  • 从第一天就是抛弃式的，标记清楚
  • 一条命令运行（用项目的 task runner）
  • 默认不持久化
  • 跳过所有打磨（无测试、最小错误处理、无抽象）
  • 每次操作/切换后展示状态

完成后：把验证过的决策折叠进真实代码，原型提交到抛弃式分支（不合并主分支），在 issue 中记录结论。

场景七：知识调研

1
/research

做什么：启动后台 Agent 调研问题，结果写为 Markdown 文件存入仓库。

规则：

  • 每条声明必须追溯到一手来源（官方文档、源码、Spec、第一方 API）
  • 文件遵循仓库已有的笔记惯例
  • Agent 在后台跑，用户可以继续工作

场景八：跨会话协作

保存交接文档

1
/handoff
  • 把当前对话压缩为 Markdown 交接文档
  • 包含 “建议调用的 Skill” 部分
  • 引用而不重复已在其他产物（Spec/Plan/ADR/Issue/Commit/Diff）中的内容
  • 脱敏（API key/密码/PII）
  • 保存到操作系统临时目录（不是当前工作空间）

立即启动后台 Agent 接手

1
/claude-handoff
  • 同上，但直接启动后台 Agent 继续工作
  • 等价于 claude --bg --name "<描述性名称>" "<交接摘要>"
  • 用户通过 claude agents 管理

场景九：教与学

1
/teach

做什么：建立多会话的教学工作空间。

文件结构：

  • MISSION.md —— 学习动机（如果不清，先盘问用户）
  • RESOURCES.md —— 高质量可信资源（绝不信任模型参数化知识）
  • ./learning-records/*.md —— 编号的 ADR 风格学习记录（最近发展区）
  • ./lessons/*.html —— 编号的自包含 HTML 课程（短小精美，含交互元素）
  • ./reference/*.html —— 压缩速查表、词汇表、算法
  • ./assets/* —— 可复用组件（样式表、测验组件、模拟器、图表 helper）
  • NOTES.md —— 用户偏好和备忘

三支柱哲学：Knowledge（可信来源）→ Skills（交互式课程+检索练习/间隔/交错）→ Wisdom（社区互动）

场景十：其他独立工具

生成交互式 Bash 向导

1
/wizard
  1. 读取仓库配置（.env、.env.example、README、docker-compose*、GitHub Actions secrets）
  2. 按阶段映射流程 —— 打开哪个 URL、做什么、捕获什么值、填入哪个变量
  3. 基于 template.sh 生成脚本（含完整的进度条、确认门、跨平台 URL 打开、隐藏输入、幂等 .env 写入）
  4. 静态验证（bash -n + shellcheck），告知用户如何运行

解决合并冲突

1
/resolving-merge-conflicts
  1. 查看当前状态（冲突文件和历史）
  2. 为每个冲突找到一手来源——深入理解每处改动的原始意图
  3. 逐块解决 —— 能保留双方意图就保留，不能就选匹配合并目标的那个
  4. 跑自动化检查（类型检查→测试→格式化）
  5. 完成 merge/rebase

路由到合适 Skill

1
/ask-matt

不知道用哪个 Skill？直接问，它会根据你的情况推荐合适的 Skill 或工作流链路。

Skill 依赖层级总结

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Layer 0（基础设施 — 被几乎所有上层 Skill 消费）
  ├── codebase-design    词汇层：模块/接口/深度/seam/adapter
  ├── domain-modeling    维护 CONTEXT.md 和 ADR
  └── grilling           无情盘问协议

Layer 1（组合 Skill — 调用 Layer 0）
  ├── grill-with-docs    = grilling + domain-modeling
  ├── triage             调用 grilling + domain-modeling
  ├── wayfinder          调用 grilling + domain-modeling + research + prototype
  └── improve-codebase-architecture  调用 codebase-design + grilling + domain-modeling

Layer 2（流程 Skill — 消费 Layer 1 的输出）
  ├── to-spec            合成对话 → 发布 Spec（消费 CONTEXT.md）
  ├── to-tickets         拆分 Spec → Ticket 链（消费 CONTEXT.md）
  └── implement          执行 ticket → tdd → code-review

Layer 3（专项 Skill — 独立或响应事件）
  ├── diagnosing-bugs    6 阶段诊断 → Phase 6 可能 handoff 给 improve-codebase-architecture
  ├── tdd                红-绿循环（消费 CONTEXT.md）→ refactor 阶段交给 code-review
  ├── code-review        双维度并行审查（Standards + Spec）
  ├── prototype          LOGIC / UI 分支原型
  ├── research           后台调研子 Agent
  ├── resolving-merge-conflicts  合并冲突解决
  └── wizard             交互式 Bash 向导生成

Layer 4（元技能 — 路由和配置）
  ├── setup-matt-pocock-skills  一次性配置入口
  ├── ask-matt           路由到合适 Skill
  ├── handoff / claude-handoff  跨会话交接
  └── teach              多会话教学框架

总结

Matt-skills非常适合强的模型，比如fable,GPT-5.6, 他的每个技能提示词非常少，强调的是让模型自身发挥更强的能力。
/grill-with-doc->/to-spec->/to-tickets->/implement。对于正常开发完全够了，中间的这几步也可以完全不用。
codex经常会触发/implement, 也就是每次让他去执行某个功能开发的时候，会触发 /implement技能，这个技能会从tdd开始然后到最后的code-review, 一个非常好的开发流程。