Matt Pocock Skills 使用指南

37 个 AI Agent 工程技能，覆盖从「想法」到「上线」的完整工作流。
安装路径：~/.agents/skills/，已 symlink 到 Hermes Agent。

---

一、核心工作流（从想法到交付）

这是最常用的主干路径，按顺序走：

想法 → grill-with-docs（打磨需求）
     → to-spec（写规格文档）
     → to-tickets（拆任务）
     → implement（实现）
     → code-review（代码审查）
     → 提交

1. grill-with-docs — 需求打磨（有文档版）

场景： 你有一个模糊的想法/需求，需要把它打磨成清晰的设计。
做什么： AI 会像面试官一样不断追问你，每轮提出一组问题并给出推荐答案。同时自动维护 CONTEXT.md（术语表）和 ADR（架构决策记录）。
用法： 在项目目录下直接说”我想要 XXX 功能”，AI 自动启动。
适合： 在已有代码仓库中做功能设计。

2. grill-me — 需求打磨（无文档版）

场景： 同上，但你不在项目目录里（比如在规划一个新项目、写文章、做决策）。
做什么： 同样的追问流程，但不写入任何本地文件。
适合： 头脑风暴、规划阶段、非代码场景。

3. grilling — 追问原语

场景： 你只想用纯粹的追问流程，不需要任何包装。
做什么： 设计树 + 前沿问题 + 轮次制。AI 负责找事实，你负责做决策。
适合： 高级用户直接调用，或者被其他 skill 内部调用。

4. to-spec — 对话转规格文档

场景： 需求讨论完了，需要把它变成正式的 spec 文档。
做什么： 综合当前对话内容，生成包含问题陈述、解决方案、用户故事、实现决策、测试决策、范围外内容的完整 spec，发布到 issue tracker。
适合： grill 完成后的下一步。

5. to-tickets — 拆分为任务

场景： Spec 写好了，需要拆成可执行的任务卡片。
做什么： 把 spec 拆成「tracer bullet」垂直切片任务，每个任务声明依赖关系（blocked by）。支持本地文件或 GitHub Issues。
适合： 大功能的并行开发。

6. implement — 实现任务

场景： 任务卡片准备好了，开始写代码。
做什么： 基于 spec 或 ticket 实现功能。内部驱动 TDD（红绿循环），完成后自动运行 code-review，最后提交。
适合： 单个 ticket 的实现。

7. implement-spec — 实现完整规格

场景： 有一整个 spec 需要实现（多个 ticket）。
做什么： 读取 spec 和关联的 tickets，创建分支和 draft PR，用子 agent 并行实现各个 ticket，最后合并、审查、标记 PR 为 ready。
适合： 大型功能的并行实现。

8. code-review — 双轴代码审查

场景： 代码写完了，需要审查。
做什么： 从两个维度并行审查：

• Standards（标准）：是否符合项目的编码规范？检测 Fowler 代码异味。
• Spec（规格）：是否忠实实现了 spec 中的需求？
  适合： PR 审查、分支审查、”review since X”。

9. tdd — 测试驱动开发

场景： 你想用红-绿-重构的方式写代码。
做什么： 强调在预定义的 seam（接口边界）上测试，一次一个垂直切片，禁止实现耦合的测试。
适合： 单独使用或被 implement 内部调用。

---

二、大型项目规划

10. wayfinder — 迷雾中的导航

场景： 项目太大，一个 session 装不下，而且路径不清晰（比如新项目启动、大型重构）。
做什么： 创建一个「地图」issue + 一系列「决策 ticket」。每个 ticket 解决一个决策问题（研究、原型、追问、执行），逐个解决直到路径清晰。产出的是决策，不是代码。
适合： 绿地项目、大型特性、复杂迁移。
关键概念： 迷雾（fog of war）、前沿（frontier）、决策票（decision tickets）。

11. triage — Issue 分诊

场景： GitHub Issues 堆积了 bug 报告和功能请求，需要分类处理。
做什么： 把 issue 推进状态机：needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix。会验证 bug 是否可复现，给 agent-ready 的 issue 写 brief。
适合： 开源项目维护、团队 issue 管理。

---

三、调试与诊断

12. diagnosing-bugs — 硬核 Bug 诊断

场景： 遇到难搞的 bug（间歇性故障、性能回退、难以复现的问题）。
做什么： 6 阶段流程：

1. 构建反馈循环（核心！）—— 找到一个能可靠触发 bug 的命令
2. 复现 + 最小化 — 缩小到最小复现场景
3. 假设 — 生成 3-5 个可证伪的假设
4. 插桩 — 逐一验证假设
5. 修复 + 回归测试 — 先写测试再修 bug
6. 清理 — 删除调试代码
   适合： 那种”看一眼搞不定”的 bug。

---

四、架构与代码质量

13. improve-codebase-architecture — 架构改进

场景： 代码库有架构债务，想系统性地改进。
做什么： 扫描代码库，找到「深化机会」（shallow module → deep module），生成 HTML 可视化报告，然后通过追问流程确定改进方案。
适合： 技术债务清理、架构重审。

14. codebase-design — 深模块设计词汇

场景： 你在设计模块接口，需要一套统一的设计语言。
做什么： 提供一套精确的术语：module、interface、depth、seam、adapter、leverage、locality。核心原则：深模块 = 小接口 + 大实现。
适合： 被其他 skill 引用，或在讨论架构时直接使用。

15. domain-modeling — 领域建模

场景： 你在讨论项目的领域术语，需要统一语言。
做什么： 挑战模糊术语、发明精确词汇、维护 CONTEXT.md 术语表、在必要时创建 ADR。
适合： DDD 实践、新项目启动时统一术语。

16. resolving-merge-conflicts — 解决合并冲突

场景： Git merge/rebase 产生了冲突。
做什么： 逐 hunk 分析双方意图，优先保留两边，不兼容时选择符合合并目标的那个。永不 --abort。
适合： 复杂冲突、不想手动处理。

---

五、原型与探索

17. prototype — 可丢弃原型

场景： 有个设计问题需要用代码回答（”这个状态模型对不对？”、”UI 应该长什么样？”）。
做什么： 两种模式：

• 逻辑原型：生成一个可交互的 HTML 文件，用按钮驱动状态机走各种路径
• UI 原型：生成多个 UI 变体，通过 URL 参数切换
  适合： 设计评审、探索性开发。

18. research — 后台调研

场景： 需要调查一个技术问题（API 文档、第三方服务、技术选型）。
做什么： 启动后台 agent，查阅一手资料（官方文档、源码、规范），输出带引用的 Markdown 调研报告。
适合： 技术选型、API 调研、可行性分析。

---

六、交接与协作

19. handoff — 会话交接

场景： 当前 session 快到上下文窗口限制了，需要把工作交给下一个 session。
做什么： 把当前对话压缩成一份交接文档，包含关键决策、待办事项、建议加载的 skill。
适合： 长任务的 session 切换。

20. claude-handoff — Claude Code 交接

场景： 同上，但专为 Claude Code 设计。
做什么： 生成交接摘要后直接启动一个后台 Claude Code agent 继续工作。
适合： Claude Code 用户。

21. to-questionnaire — 生成问卷

场景： 你需要从别人那里获取信息（比如问产品经理需求细节、问运维环境配置）。
做什么： 追问你「发给谁」和「需要什么回来」，然后生成一份结构化的问卷文档。
适合： 跨团队沟通、异步协作。

---

七、写作相关

22. writing-fragments — 素材探索

场景： 你想写一篇文章，但还在收集素材阶段。
做什么： AI 追问你，把对话中涌现的片段（句子、场景、比喻、半成品想法）记录到 Markdown 文件。
适合： 写作前期的头脑风暴。

23. writing-shape — 素材成型

场景： 素材收集完了，需要把它组织成文章。
做什么： 逐段讨论、逐段落写入。AI 会追问”这段对读者有什么用？”、”如果删掉会怎样？”。
适合： 从素材到成稿。

24. writing-beats — 节拍式写作

场景： 同上，但用「节拍」（beat）为单位，选择你自己的冒险路线。
做什么： 每个节拍是一个叙事动作。先确定前置知识，然后每个节拍引入新概念，用户选择下一个节拍的方向。
适合： 教程、叙事性文章。

25. writing-for-agents — 为 Agent 写文档

场景： 你在写 skill、AGENTS.md、CLAUDE.md 等 Agent 消费的文档。
做什么： 参考指南，教你如何写「上下文指针」、「信息层级」、「前置词」、「完成标准」等。
适合： Skill 作者、Agent 配置。

---

八、教学与学习

26. teach — 多 session 教学

场景： 你想系统学习一个主题。
做什么： 创建教学工作区：MISSION.md（学习目标）、lessons/（课程）、reference/（参考文档）、learning-records/（学习记录）。基于「最近发展区」理论设计课程。
适合： 系统学习新技能。

27. scaffold-exercises — 练习脚手架

场景： 你在做课程开发，需要创建练习目录结构。
做什么： 按规范创建 exercises/ 目录，包含 problem/、solution/、explainer/ 子目录。
适合： 课程/教程开发。

---

九、项目初始化与配置

28. setup-matt-pocock-skills — 初始化配置

场景： 第一次使用这套 skill，需要配置 issue tracker、triage 标签、领域文档布局。
做什么： 探索仓库现状，询问你用什么 issue tracker（GitHub/GitLab/本地文件），配置标签映射，设置 CONTEXT.md 和 ADR 目录。
适合： 新项目首次配置（必须先跑这个）。

29. setup-ts-deep-modules — TypeScript 深模块配置

场景： TypeScript 项目想强制执行深模块架构。
做什么： 安装 dependency-cruiser，配置规则：只允许通过入口文件导入，子目录内部自由导入。
适合： TypeScript monorepo 架构治理。

30. setup-pre-commit — Pre-commit 钩子

场景： 想在提交前自动格式化、类型检查、跑测试。
做什么： 安装 Husky + lint-staged + Prettier，配置 pre-commit hook。
适合： 代码质量门禁。

31. git-guardrails-claude-code — Git 安全护栏

场景： 防止 Claude Code 执行危险的 git 命令（push、reset –hard、clean 等）。
做什么： 安装 PreToolUse hook，拦截并阻止危险命令。
适合： Claude Code 安全防护。

---

十、其他独立工具

32. wait-what — 没听懂，再说一遍

场景： AI 说的东西你没理解。
做什么： AI 用更简单的语言重新解释，使用 CONTEXT.md 的术语。
适合： 任何时候觉得 AI 的回答太晦涩。

33. loop-me — 工作流设计

场景： 你想设计自动化工作流（比如每日报告、邮件处理、issue 分拣）。
做什么： 追问你生活/工作中的重复模式（loop），设计成可委托给 AI 的 workflow spec。
适合： 流程自动化设计。

34. retro — 会话复盘

场景： 一个 coding session 结束了，想改进 Agent 的工作环境。
做什么： 分析 session 日志，从导航、自动化检查、编码标准、工具效率等维度提出改进建议。
适合： 持续改进 Agent 工作环境。

35. ask-matt — Skill 路由器

场景： 不确定该用哪个 skill。
做什么： 根据你的当前情况，推荐应该走哪条路径。
适合： 新手入门。

36. migrate-to-shoehorn — 测试代码迁移

场景： TypeScript 测试代码里到处是 as 类型断言，想换成类型安全的方式。
做什么： 安装 @total-typescript/shoehorn，把 as Type 替换为 fromPartial()。
适合： TypeScript 测试代码质量提升。

37. grill-with-docs vs grill-me 选择指南

场景	用哪个
在项目目录中做功能设计	grill-with-docs（写入 CONTEXT.md + ADR）
规划新项目、写文章、非代码决策	grill-me（无状态，不写文件）
只要追问流程本身	grilling（原语）

---

十一、速查表：按场景找 Skill

你想做什么	用什么
打磨一个模糊想法	grill-with-docs 或 grill-me
把对话变成 spec	to-spec
拆分任务	to-tickets
写代码	implement / implement-spec
代码审查	code-review
测试驱动开发	tdd
调试难搞的 bug	diagnosing-bugs
改进架构	improve-codebase-architecture
大项目规划	wayfinder
Issue 分诊	triage
做原型验证	prototype
调研技术方案	research
Session 切换	handoff / claude-handoff
从别人那里问信息	to-questionnaire
写文章	writing-fragments → writing-shape / writing-beats
学新东西	teach
统一术语	domain-modeling
解决 merge 冲突	resolving-merge-conflicts
不确定用啥	ask-matt

---

十二、主干流程图

                  ┌─────────────┐
                  │  你有一个想法  │
                  └──────┬──────┘
                         ▼
                ┌─────────────────┐
                │ grill-with-docs  │  ← 打磨需求
                │ 
                └────────┬────────┘
                         ▼
            ┌───── 需要代码原型？─────┐
	  │ 是                                                │ 否
            ▼                                                    ▼
   ┌──────────────┐       ┌──────────────┐
   │   prototype   │                                      │   继续对话    │
   │ (throwaway)   │       └──────┬───────┘
   └──────┬───────┘              │
          │ handoff 回来          │
          └──────────┬───────────┘
                     ▼
            ┌─────────────────┐
            │     to-spec      │  ← 写规格
            └────────┬────────┘
                     ▼
            ┌─────────────────┐
            │    to-tickets    │  ← 拆任务
            └────────┬────────┘
                     ▼
       ┌─────────────┴─────────────┐
       │ 多个 ticket               │ 单个 ticket
       ▼                           ▼
┌──────────────┐          ┌──────────────┐
│ implement-spec│          │  implement   │
│ (并行子 agent) │          │              │
└──────┬───────┘          └──────┬───────┘
       └─────────────┬───────────┘
                     ▼
            ┌─────────────────┐
            │   code-review    │  ← 双轴审查
            └────────┬────────┘
                     ▼
            ┌─────────────────┐
            │     提交 PR      │
            └─────────────────┘

---

笔记创建时间：2026-08-30
来源：github.com/mattpocock/skills