Matt Pocock's Skills — Agent 技能库完全使用指南

一份详细的安装、配置、逐技能使用手册和实战技巧，覆盖 mattpocock/skills 的全部 35 个技能。
常用度标注：⭐⭐⭐ 高频（几乎每天用） · ⭐⭐ 中频 · ⭐ 低频/一次性配置。

这是什么

mattpocock/skills 是 Matt Pocock（Total TypeScript 作者、AI Hero 站长）开源的一套 coding agent skills 集合，MIT 协议。它源自作者的 .agents 目录，核心理念是：技能要 "small, easy to adapt, and composable"——小而易于改造、可组合。它不绑定特定模型，配合 Claude Code、Codex 等任何 agent harness 使用。

这套技能针对 coding agent 的 四个典型失败模式 对症下药：

| 失败模式 | 症结 | 技能解法 |
|---|---|---|
| Agent 没做你想要的 | 需求没对齐 | 先开 grilling session 拷问式访谈（/grill-me / /grill-with-docs） |
| Agent 太啰嗦 | 没有共享语言 | 建 CONTEXT.md 词汇表 + ADR，让 agent 用项目的行话交流 |
| 代码不工作 | 没有反馈循环 | 静态类型、自动化测试、/tdd、/diagnosing-bugs |
| 代码变成大泥球 | 设计失控 | to-spec、improve-codebase-architecture 持续关注设计 |

---

安装

两种方式，任选其一——作者特别强调："Pick one — installing both leaves you with every skill twice."（装两个会得到每个技能两份）。

方式一：Claude Code 插件（推荐，只读托管、自动更新）

claude plugins install mattpocock-skills

或在 Claude Code 会话内直接输入：

/plugin install mattpocock-skills

方式二：skills.sh（可编辑，复制进项目可自行修改）

npx skills@latest add mattpocock/skills

安装器会交互式询问：选择哪些技能、安装到哪些 agent。务必勾选 setup-matt-pocock-skills——它是其他所有技能的前置配置。

之后拉取作者更新：

npx skills update

安装后位于 ~/.claude/skills/（或插件管理的只读位置），每个技能一个目录，内含 SKILL.md（技能本体，纯 prompt 指令）+ 辅助文件（模板、脚本、子文档）。

---

初始化配置（每个仓库一次）

/setup-matt-pocock-skills

它会问你三件事并写入 docs/agents/：

1. Issue tracker：问题追踪器放哪——GitHub（默认，走 gh CLI）、GitLab、本地 markdown（.scratch/<feature>/，适合个人项目），或自定义（Jira/Linear 用一段话描述工作流）。
2. Triage 标签词汇：/triage 用的五个状态标签，默认 needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix，已有约定时可覆盖。
3. 领域文档布局：默认单上下文（根目录 CONTEXT.md + docs/adr/）；Monorepo 可选多上下文（CONTEXT-MAP.md 指向各子包自己的 CONTEXT.md）。

完成后它会在你的 CLAUDE.md / AGENTS.md 里写入一个 ## Agent skills 区块，让 agent 每次启动都能看到这些约定。

---

技能总览

这套技能最妙的设计是 /ask-matt——它本身就是一张导航图。绝大多数工作沿一条主干流前进，两条入口匝道汇入其上，其余是独立工具和底层词汇层。

/grill-with-docs ─→ /to-spec ─→ /to-tickets ─→ /implement ─→ /code-review
   (打磨想法)       (写成规格)    (拆成票证)      (逐个实现)    (双轴评审)
                      ▲                             │
                      │           内部驱动            │
                      └──────────/tdd 红绿循环 ◀────┘

所有技能按其学习顺序分组如下，每组内给出何时使用和如何使用。标注顺序即推荐学习顺序。

全技能速查表

一页扫完 35 个技能：名称 / 一句话作用 / 常用度。常用度：⭐⭐⭐ 高频（几乎每天用）· ⭐⭐ 中频 · ⭐ 低频/一次性配置。

| 技能 | 一句话作用 | 常用度 |
|---|---|---|
| 一、主干流程 | | |
| /grill-with-docs | 打磨想法，边问边把术语写进 CONTEXT.md | ⭐⭐⭐ |
| /to-spec | 把对话综合成 spec 并发布到追踪器 | ⭐⭐⭐ |
| /to-tickets | spec 拆成曳光弹垂直切片票证 | ⭐⭐⭐ |
| /implement | 按票证实现，驱动 /tdd + /code-review 收尾 | ⭐⭐⭐ |
| /code-review | Standards/Spec 双轴并行评审 diff | ⭐⭐⭐ |
| 二、入口匝道 | | |
| /triage | 外部 issue/PR 分类、验证、打标签 | ⭐⭐ |
| /diagnosing-bugs | 硬 bug/性能回退的六阶段纪律诊断 | ⭐⭐⭐ |
| /wayfinder | 巨型模糊项目按决策票逐步摸清 | ⭐ |
| 三、底层词汇层 | | |
| /codebase-design | 深模块设计词汇（接口/Depth/Seam） | ⭐⭐ |
| /domain-modeling | 挑战含糊术语，维护 CONTEXT.md/ADR | ⭐⭐ |
| 四、独立工具 | | |
| /grill-me | 无工作目录时的纯访谈（/grilling 无状态版） | ⭐⭐⭐ |
| /grilling | 访谈原语：决策树逐轮推进 | ⭐⭐⭐ |
| /handoff | 会话压成交接文档（存系统临时目录） | ⭐⭐ |
| /claude-handoff | 交接后直接派后台 agent 干活 | ⭐⭐ |
| /prototype | 丢弃式原型：逻辑/UI 分支做给真人看 | ⭐⭐ |
| /research | 后台 agent 查一手来源并产出引用笔记 | ⭐⭐ |
| /to-questionnaire | 给领域专家生成决策问卷 | ⭐ |
| /wizard | 生成真人步骤向导 bash 脚本 | ⭐⭐ |
| /wait-what | 没听懂时要求用简化英语重讲 | ⭐⭐ |
| /teach | 把我当前目录变教学空间，多会话学技能 | ⭐⭐ |
| /loop-me | 把生活循环写成可执行工作流 spec | ⭐ |
| /resolving-merge-conflicts | 逐 hunk 按意图调 merge 冲突，永不 --abort | ⭐⭐ |
| 五、环境与工程质量（配置类） | | |
| /setup-matt-pocock-skills | 每仓库一次：追踪器/标签/文档布局 | ⭐⭐⭐ |
| /setup-pre-commit | 加 Prettier+类型检查+测试预提交钩子 | ⭐⭐ |
| /setup-ts-deep-modules | 让每个 TS 包成深模块（dependency-cruiser） | ⭐ |
| /git-guardrails-claude-code | 拦截 push/reset/clean 等危险 git 命令 | ⭐ |
| 六、工程质量（开发循环内） | | |
| /tdd | 红-绿-重构循环，垂直切片推进 | ⭐⭐⭐ |
| /improve-codebase-architecture | 扫描深化机会，产出 HTML 体检报告 | ⭐⭐ |
| /migrate-to-shoehorn | 测试里 as 断言迁移到类型安全 shoehorn | ⭐ |
| /scaffold-exercises | 搭建练习课程目录结构 | ⭐ |
| 七、写作类 | | |
| /writing-fragments | 探索态：收集碎片与造词，不承诺结构 | ⭐ |
| /writing-shape | 开采态：把材料逐段塑形成文 | ⭐ |
| /writing-beats | 开采态：choose-your-own-adventure 节拍旅程 | ⭐ |
| /writing-for-agents | 给 agent 写文档/技能时的写作手法 | ⭐ |
| 八、路由与导航 | | |
| /ask-matt | 不确定用哪个技能时问它 | ⭐⭐ |

常用技能推荐

高频必备（⭐⭐⭐，日常开发几乎必用）——共 8 个：setup-matt-pocock-skills（一次配置）、grill-with-docs、to-spec、to-tickets、implement、code-review、tdd、diagnosing-bugs。另加两个无工作目录时的访谈工具 grill-me / grilling。跑熟这 10 个，你就吃透了整套库的 90%。

按场景推荐：

• 新仓库起步：setup-matt-pocock-skills → grill-with-docs（打磨）+ domain-modeling（同步维护词汇表）
• 日常写功能：grill-with-docs → to-spec → to-tickets → implement（内嵌 tdd）→ code-review
• 硬 bug / 性能退化：diagnosing-bugs（六阶段：先建红反馈循环再动手）
• 外部 issue 涌入：triage → grill-with-docs
• 巨型模糊项目：wayfinder → 过渡到主干流程
• 阶段交接：handoff（要文档）或 claude-handoff（立刻派后台 agent）
• 定期体检：improve-codebase-architecture（作者建议每几天一次）

不确定任何一步该用什么？先问 /ask-matt——它就是导航图。

---

一、主干流程（idea → ship）

/grill-with-docs ⭐⭐⭐ 有工作目录时的首选起点

作用：通过一轮轮不留情面的提问，把模糊想法打磨成共识，同时把术语写进 CONTEXT.md、关键决策记成 ADR。

• 何时使用：每次做变更前。在仓库里开始任何新功能、新模块、不小的一次改动时，先开它。它是状态化的，会在仓库里留下文档痕迹。
• 如何使用：直接输入 /grill-with-docs，然后回答它一轮轮的提问。每轮它会把当前可问的决策全部列出来并附上推荐答案，你逐个确认或否决，直到所有分支都聊完。结束后 CONTEXT.md 和 ADR 已就位，你得到一个打磨过的需求。
• 注意：和它配套的领域模型维护由 /domain-modeling 完成，通常自动联动，无需手动调用。

/to-spec ⭐⭐⭐ 会话 → 规格

• 何时使用：打磨完想法、要进入多会话构建时；或会话里已经讨论透了、想落成正式 spec 存档时。
• 如何使用：输入 /to-spec 即可。它不再提问，直接综合当前对话上下文合成一份 spec（Problem Statement / 长列表 User Stories / 实现决策 / 测试决策 / Out of Scope），发布到步骤「初始化配置」选定的追踪器，并自动打上 ready-for-agent 标签。
• 注意：spec 里不含具体文件路径和代码片段（容易过期）；如果原型产生了关键代码形态（状态机、schema），可以例外内联。

/to-tickets ⭐⭐⭐ 规格 → 拆分票证

• 何时使用：拿到 spec 或计划，要把工作拆成可逐个执行的单元时。
• 如何使用：输入 /to-tickets，它会给出每个票证的标题、阻塞关系、交付内容，并先问你拆分粒度对不对、阻塞边对不对，确认后才发布到追踪器。每张票是曳光弹垂直切片——贯穿所有层、独立可演示、能塞进一个全新上下文窗口。
• 注意：宽重构（全局改名/改类型）会被拆成 expand–contract 三步序列，不要硬塞进垂直切片。

/implement ⭐⭐⭐ 按 spec/票证实现

• 何时使用：拿到一张"ready-for-agent"的票证或一份 spec 要动手写代码时。
• 如何使用：输入 /implement。它内部驱动 /tdd 在预先议定的 seam 处红绿循环，频繁跑类型检查和单测，最后跑全量测试，结束用 /code-review 评审，然后提交到当前分支。
• 注意：每张票开新会话执行（上一张的上下文可丢弃）；可协商跳过 /tdd 的 seam 只有在你说过之后才生效。

/code-review ⭐⭐⭐ 双轴评审

• 何时使用：review 一个分支、PR、或 WIP 变更时；想对 HEAD 与某个固定点之间的 diff 做评审时。
• 如何使用：输入 /code-review 并指定固定点（commit SHA、分支、tag、main、HEAD~5）。它将 diff 交给两个并行子代理：Standards 轴（对照仓库编码规范 + 12 项 Fowler 坏味道基线）和 Spec 轴（对照来源 issue/spec）。结果两栏并排展示，不合并不排重——防止一轴掩盖另一轴。
• 注意：如果找不到 spec，会问你；仓库没有编码规范时，坏味道基线仍照常工作。

---

二、入口匝道（On-ramps）

/triage ⭐⭐ 外部 issue/PR 分流

• 何时使用：bug 报告、需求请求、外部 PR 源源不断进来，需要先分类、验证、写清楚再交给 agent 时。只处理你没创建的 issue（/to-tickets 产出的票已 agent-ready，不需要 triage）。
• 如何使用：输入 /triage 并说明意图（"看看有什么要处理的" / "处理 #42"）。它会展示三个桶（未标记、needs-triage、need-info 有回复的），帮你从分类 → 验证（复现 bug / 跑 PR 的测试）→ 必要时 grilling → 打上状态标签并写 agent 简报。所有 AI 发的评论带免责声明前缀。
• 注意：状态机默认 needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix；标为 wontfix 的拒绝需求会归档到 .out-of-scope/ 知识库防止重复建议。

/diagnosing-bugs ⭐⭐⭐ 硬 bug 诊断

• 何时使用：遇到的 bug 不是一眼能看穿的——间歇性 flake、两个已知良好状态之间悄悄引入的回退、性能退化。简单 bug 直接修，把这条纪律留给硬骨头。
• 如何使用：输入 /diagnosing-bugs。流程六阶段：① 构建紧致反馈循环（一条能在此 bug 上变红的命令，没这个不许进入下一步）→ ② 复现并最小化 → ③ 生成 3-5 个可证伪假设并给你看 → ④ 逐变量插桩 → ⑤ 先写回归测试再修 → ⑥ 清理（删调试日志、原型归档、提交信息里说明正确假设）。
• 注意：如果代码库没有"正确的 seam"来锁定这个 bug，这本身就是一个发现——会被当作架构问题上交，这正是它衔接 /improve-codebase-architecture 的原因。

/wayfinder ⭐ 巨型模糊项目的地图

• 何时使用：绿场项目、超大功能，大到单个 agent 会话装不下、路都看不清时。别用于范围明确的普通功能（那是 /grill-with-docs 的活）。
• 如何使用：输入 /wayfinder 描述想法。它先 grilling 定下"目的地"，再广度优先摸清前沿，在追踪器上创建一张决策票地图（每票 resolve 一个决策而非交付物），逐票推进，路线清晰后移交 /to-spec。一次会话只解析一张票。
• 注意：research 类型的票会并行派后台 agent 解决；HITL 票（原型、访谈）必须真人参与。

---

三、底层词汇层（其他技能的共享语言）

/codebase-design ⭐⭐ 深模块设计词汇

• 何时使用：设计或重构模块接口、找深化机会、决定 seam 放哪、想让代码更好测/更好被 AI 导航时；或其他技能需要深模块词汇时（/tdd、/improve-codebase-architecture 内部都讲这套话）。
• 如何使用：这是一份参照词汇表而非会话流程——告诉 agent "用 codebase-design 的语言"即可。它定义 Module / Interface / Depth / Seam / Adapter / Leverage / Locality 七个词，以及"删除测试"、"接口即测试面"、"一个 adapter 是假设性 seam，两个才是真的"等判断。

/domain-modeling ⭐⭐ 领域语言打磨

• 何时使用：讨论代码库术语、写或改 CONTEXT.md、记录或修改 ADR 时；术语含糊、一个词多个意思、或代码与说法矛盾时。
• 如何使用：主动 discipline——挑战模糊术语（"你说 account，是 Customer 还是 User？"）、用具体场景压力测试领域关系、对照代码找矛盾。确认一个词就立刻更新 CONTEXT.md，不攒批。
• 注意：ADR 只在这三条同时成立才写：难以逆转、无上下文会困惑、真是权衡的结果。

---

四、独立工具（Standalone）

/grill-me ⭐⭐⭐ 无工作目录时的访谈

• 何时使用：不在工作目录里打磨计划、设计、文章时（grill-with-docs 的无状态版，不存任何东西）。
• 如何使用：输入 /grill-me 即可——内部等价于调用 /grilling。它在仓库里就选 /grill-with-docs（会留下文档，严格更好），别在这里用它。

/grilling ⭐⭐⭐ 访谈原语

• 何时使用：想要"纯访谈、不带任何包装"时；作为其他技能的底层引擎（你通常不必直接调用）。
• 如何使用：把设计决策映射成决策树，按轮次工作：每轮问清当前"前沿"（所有前置已定的决策），逐条编号并列推荐答案，等你答完再进下一轮。树空即结束，不确认共识不行动。

/handoff ⭐⭐ 会话交接文档

• 何时使用：在阶段边界要交接给新会话、新目录、同事，或分叉一个侧线任务中途时。它买的是可携带性。
• 如何使用：输入 /handoff（可带参数说明下个会话的焦点）。它把对话压成一份 Markdown（存系统临时目录，不污染仓库），含 "suggested skills" 区块，脱敏敏感信息，不重复已有文档只引用。

/claude-handoff ⭐⭐ 交接并立即派活

• 何时使用：同样场景，但你要的是"立即有后台 agent 接手干活"而非"生成文件让你手动打开"。
• 如何使用：输入 /claude-handoff。它写交接摘要后直接 claude --bg --name "<名字>" "<摘要>" 启动一个后台 agent（从当前目录启动），用 claude agents 管理。

/prototype ⭐⭐ 丢弃式原型

• 何时使用：设计问题在纸上谈不拢时——状态/业务逻辑"感觉对吗"、UI"该长什么样"。它的产出是给真人看的。
• 如何使用：选择问题分支（逻辑 vs UI）由技能自动判断或问你。逻辑分支 → 单个可分享 HTML（操作按钮 + 引导演练）；UI 分支 → 同一路由下多个风格变体，URL 参数切换。完成后决策并入正式代码，原型提交到 prototype/<name> 分支留作 primary source。

/research ⭐⭐ 后台调查

• 何时使用：要查证一个话题、收集 API 事实、把阅读苦力派给后台 agent 时。
• 如何使用：输入 /research 说明问题。技能会启动后台 agent 查一手来源（官方文档、源码、spec，不采信二手转述），把带引用的结论写成一个 Markdown 文件放进仓库已有的笔记约定位置。你继续干别的活。

/to-questionnaire ⭐ 决策问卷

• 何时使用：卡住你的不是自己或代码库，而是别人脑子里的知识（被采访对象是领域专家/干系人）时。
• 如何使用：输入 /to-questionnaire。它只采访你关于发送对象（发给谁、需要回什么），然后写出对准信息差的问卷 to-questionnaire-<slug>.md。回收的答案是 /grill-with-docs 或 /to-spec 的素材。

/wizard ⭐⭐ 真人步骤向导

• 何时使用：只有人能做的步骤——配置基础设施、填 CI 密钥、走陌生的第三方仪表盘、一次性迁移/切换。agent 自己能做的不要用它。
• 如何使用：输入 /wizard 描述流程。它生成一个交互式 bash 脚本：逐阶段开 URL → 提示点击/复制 → 捕获值写入 .env 和 GitHub secrets → 每步确认并显示剩余阶段。脚本内置确认门、密钥隐藏录入、幂等更新。

/wait-what ⭐⭐ 听不懂就重新讲

• 何时使用：agent 上一条消息没讲明白、你没跟上时。会话中途、任何技能内部都能用。
• 如何使用：输入 /wait-what。agent 会用简化技术英语（ASD-STE100）+ CONTEXT.md 词汇重新阐述一遍刚才的内容。它治已发生；/grill-with-docs 是治未然（提前对齐语言）。

/teach ⭐⭐ 跨会话教学

• 何时使用：要学一个新技能/概念，而且打算分多个会话学完（技能把当前目录变成状态化教学空间）时。
• 如何使用：输入 /teach 并说明想学什么。工作区产生 MISSION.md（为何学）、lessons/0001-.html（交互式单节课程）、reference/.html（打印友好的速查表）、learning-records/*.md（类似 ADR 的学习记录）。每课都在"最近发展区"挑战你，用检索练习/间隔/交错建立长期记忆。

/loop-me ⭐ 工作流 spec

• 何时使用：你想把自己生活中的循环模式（每周例行、每天早晨流程）委托给 AI，先把它写成一个可执行的工作流 spec 时。
• 如何使用：输入 /loop-me（可从空开始让它找循环，或直接说一个工作流）。它跑状态化 grilling，唯一产出是 workflows/*.md 工作流 spec + NOTES.md（关于你世界的原始笔记）。spec 完成后实现者 agent 能零提问直接做。

/resolving-merge-conflicts ⭐⭐ 冲突解决

• 何时使用：正在一个进行中的 merge/rebase 冲突里时（独立于任何流程，随时可用）。
• 如何使用：输入 /resolving-merge-conflicts。技能逐 hunk 处理：先看当前状态 → 为每个冲突找两侧的原始意图（读 commit、PR、issue）→ 尽量保留双方意图，不可调和时选符合合并目标的一方并注明代价 → 跑项目自动化检查 → 完成合并/继续 rebase。永不 --abort。

---

五、环境与工程质量（配置类）

/setup-matt-pocock-skills ⭐⭐⭐ 前置配置（每个仓库一次）

• 何时使用：第一次在这个仓库使用任何工程技能之前；想换 issue 追踪器时重跑。
• 如何使用：输入 /setup-matt-pocock-skills，回答追踪器、标签、文档布局三个问题（见「初始化配置」）。之后可手动编辑 docs/agents/*.md 微调，不用重跑。

/setup-pre-commit ⭐⭐ 提交前钩子

• 何时使用：想给当前仓库加 commit 时格式化（Prettier）、类型检查、测试的预提交钩子时。
• 如何使用：输入 /setup-pre-commit。自动检测包管理器，安装 Husky + lint-staged + Prettier，写 .husky/pre-commit（先 lint-staged 再 typecheck 再 test）、.lintstagedrc、.prettierrc（缺才建），核验后提交一个 "Add pre-commit hooks" 提交（提交本身会过一遍钩子当冒烟测试）。

/setup-ts-deep-modules ⭐ TS 深模块边界

• 何时使用：TS 仓库里想让每个包成为深模块——实现藏在子目录、只有根入口文件可被外部导入时。一次性配置。
• 如何使用：输入 /setup-ts-deep-modules。安装 dependency-cruiser，写 .dependency-cruiser.cjs 四条 error 规则（入口边界 / 包内自由 / 测试走入口 / 无循环），加 lint:boundaries 脚本并并入 check，建示例包，最后三步证明规则咬人：干净通过 → 临时深导入必须失败 → 还原通过。

/git-guardrails-claude-code ⭐ 危险 git 命令拦截

• 何时使用：想防止 Claude（或你自己手滑）执行 git push、reset --hard、clean -f、branch -D、checkout . 时。
• 如何使用：输入 /git-guardrails-claude-code。选择项目级或全局范围，技能复制钩子脚本、合并进 settings.json 的 PreToolUse，最后用一条测试命令验证拦截生效。

---

六、工程质量（开发循环内）

/tdd ⭐⭐⭐ 测试驱动开发

• 何时使用：要用红-绿-重构循环构建功能或修 bug 时；提到"test-first"、"red-green-refactor"、想要集成测试时。
• 如何使用：输入 /tdd 前先和 agent 议定要测的 seams（这是硬性要求，没确认的 seam 不写测试）。然后每轮：一条失败测试（红）→ 最少代码让它过（绿）→ 下一轮。垂直切片推进，禁止"先写完所有测试再写实现"。
• 注意：期望值必须来自独立来源（字面量、手算例子），不允许用和代码相同方式算出来的断言；重构不属循环，属 /code-review 阶段。

/improve-codebase-architecture ⭐⭐ 架构体检

• 何时使用：作者建议每几天跑一次，有闲时给代码库做扫描，提高 agent 在里面的可操作性。
• 如何使用：输入 /improve-codebase-architecture（可带方向，如指定模块或痛点）。它扫描热点、找"深化机会"，输出可视化 HTML 报告（写到系统临时目录并打开：before/after 图、推荐强度徽章、Top 推荐），你挑一个候选，它用 /grilling 逐项访谈并随行更新领域文档。
• 注意：它只提候选不先提接口方案；与既有 ADR 冲突的只在摩擦真实存在时提醒重议。

/migrate-to-shoehorn ⭐ 测试断言迁移

• 何时使用：想把测试里的 as 断言换成 @total-typescript/shoehorn 的类型安全替代时；测试里大量"为了填满整个对象"而伪造数据时。
• 如何使用：输入 /migrate-to-shoehorn。它指导安装 shoehorn，然后把 as Type → fromPartial()（部分数据），as unknown as Type → fromAny()（故意传错数据），fromExact()（强制完整对象），跑类型检查验证。仅限测试代码。

/scaffold-exercises ⭐ 练习课程脚手架

• 何时使用：要搭建练习目录结构（章节/练习/问题/解答/讲解）且要过 lint 时。
• 如何使用：输入 /scaffold-exercises 并给计划。按 XX-section-name / XX.YY-exercise-name 建目录，每个 problem/、solution/、explainer/ 附非空 readme.md，跑 pnpm ai-hero-cli internal lint 校验。移动练习用 git mv 保留历史。

---

七、写作类

/writing-fragments ⭐ 写作 · 探索态

• 何时使用：动笔前扩大可能性空间——收集碎片、金句、比喻、leading word，不承诺任何结构时。
• 如何使用：输入 /writing-fragments（可带保存路径）。它跑一场产出碎片的 grilling；双方聊出的每一块都静默追加进一个 markdown 文件（--- 分隔，无标题无标签）。最有价值的是 leading word——给反复出现的想法造一个词，整个结构都能挂上去。

/writing-shape ⭐ 写作 · 开采态

• 何时使用：已经有原始材料（碎片、文字墙、访谈稿）要逐段塑形成文时。材料文件对它只读。
• 如何使用：输入 /writing-shape 并给材料路径。先读透材料 → 定读者前置概念 → 给 2-3 个候选开头（各暗示不同论点）逼你选或杂交 → 此后每步问"读者下一步需要听什么"，从材料里挖料填空，讨论格式（散文 vs 列表 vs 引用 vs callout——每个格式选择要有理由）→ 边谈边追加。

/writing-beats ⭐ 写作 · 节拍式旅程

• 何时使用：同样开采态，但想要 choose-your-own-adventure 式的节拍旅程、每次只写一个节拍并让你选路时。
• 如何使用：输入 /writing-beats 并给材料路径。先定接地集（读者自带知道的概念），然后每轮给 2-3 个候选下一节拍（每个只能依赖已接地的概念，并注明它新接地什么），你选一个它写一个进文件，写完重读磁盘再提下一轮。文章在旅程自然完结时结束，材料剩多少无所谓。

/writing-for-agents ⭐ 给 agent 写作参考

• 何时使用：创建或编辑 skill、修改 AGENTS.md / CLAUDE.md、写任何 agent 消费的文档时。
• 如何使用：输入 /writing-for-agents 当参照。核心手法：context pointer（指针措辞决定触发时机，前端放 leading word）、双负载（上下文负载 vs 认知负载）、信息层级（in-file step → reference → disclosed reference，渐进披露）、用模型预训练里已有的词锚定行为而不发明新词、正面指令代替否定（"别想大象"条款）。

---

八、路由与导航

/ask-matt ⭐⭐ 技能路由

• 何时使用：不确定该用哪个技能/流程时——它是整套库的导航图。
• 如何使用：输入 /ask-matt，它会先判断你的处境（是否有工作目录、多会话还是单会话、是否已有 inbound issue），再指出该走的分支和需要调用的技能。新手期尤其有用；熟悉后会自然跳过它。

---

实战技巧

1. 先对需求，再写代码

作者原话：每次做变更前都用 grill 技能。 在仓库里用 /grill-with-docs（会留下文档），不在仓库里用 /grill-me。一次 10 分钟的访谈，省掉的是 agent 做错方向的整段返工。

2. 上下文窗口的纪律

• 打磨 → spec → 票证这三步要保持在一个不打断的上下文窗口里，别中途 /clear，让思考连贯。
• 之后每张票开新会话实现——票证自包含，上一张的上下文可丢弃。
• 阶段边界按优先级选：Continue（默认）→ Subagent → /compact → /handoff → /clear。不到万不得已不 /clear。

3. 记住"三对双胞胎"

这套库有三对替代方案，用错会浪费一半价值：

| 场景 | 应该用 | 不要用 |
|---|---|---|
| 在仓库里 vs 仓库外 | /grill-with-docs | /grill-me |
| 交接成文件 vs 立即派后台 | /handoff | /claude-handoff（除非要立刻派活） |
| 逐段塑形 vs 节拍式旅程 | 看材料形态和你的偏好 | 混用 |

4. 让词汇表成为契约

CONTEXT.md 是纯词汇表（禁止实现细节、禁止当 spec 用）。grilling 结束前确保关键术语都已收录。agent 用你的行话说话，输出立刻"像人写的"。

5. 用 /improve-codebase-architecture 定期体检

作者建议每几天跑一次。它扫描找"深化机会"，生成可视 HTML 报告你挑一个，再 grilling 到成型。防止代码变泥球的前瞻性投入。

6. 按失败模式反向选技能

• 觉得 agent"没懂我" → /wait-what 或重开 /grill
• 觉得 agent"方向不对" → 检查 seams 是否预先议定（/tdd）；配合 /code-review 的 Spec 轴
• 觉得"重构像拆炸弹" → /diagnosing-bugs 的反馈循环精神
• 觉得"架构越来越乱" → /improve-codebase-architecture + /codebase-design

7. 新手指南：先跑通这条最小路径

/setup-matt-pocock-skills（一次性）
    ↓
/grill-with-docs → /to-spec → /to-tickets → /implement → /code-review
    ↓
遇到硬 bug 用 /diagnosing-bugs；代码库每几天跑 /improve-codebase-architecture

跑通一次主干，你就理解了 90% 的库；剩下的技能都是这条主干的旁支和优化。

---

实战示例：从零创建一个新项目

下面用一个虚构但真实的场景，把主干流程完整走一遍。场景设定：

背景：你是独立开发者。决定做一个"开发者习惯打卡" SaaS——用户每天打卡三个习惯（学习、运动、写作），月底出一份统计报告。Monorepo：apps/web（Next.js）+ apps/api（Hono，带 Redis 持久化）。
前提：git init 完，仓库是空的，但 CLAUDE.md 已存在（README 说了，技能只编辑已有文件，不会新建）。

第 1 步：一次性配置（~2 分钟）

• Issue tracker → 本地 markdown（gh 还没配好，本地方案对独立开发最轻）
• Triage 标签 → 默认（needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix）
• 领域文档 → 单上下文（根目录 CONTEXT.md + docs/adr/）

结果：写入 docs/agents/issue-tracker.md、docs/agents/domain.md，并在你的 CLAUDE.md 里插入 ## Agent skills 区块。此刻起，追踪器、标签词汇、文档布局就位，一切可追溯。

第 2 步：打磨想法（~20 分钟）

你：/grill-with-docs

这是主干第一站。它开始一轮一轮提问，你会看到类似这样的决策树前沿（每问都带推荐答案）：

第 1 轮（当前可问的前沿）：
 1. 打卡频次？推荐：每天一次，日内可补多次（catch-up）
 2. 三个习惯是固定还是用户自定义？推荐：固定三个（MVP 砍掉自定义）
 3. 统计口径？推荐：按"天数达标"而非"次数"
 4. 单用户还是多用户？推荐：MVP 单用户，架构预留多用户

你逐条确认/否决。到第 3 轮，话题来到"超时/逾期怎么算"。你随口说了句"逾期后当天还让打卡吗？"——domain-modeling 立刻接管：

"等一下，你的 CONTEXT.md 里 打卡 还没定义。你刚才说的意思是——先打卡后统计，还是先判逾期再决定能否打卡？我建议把 打卡 定义为 用户在当天内为某个习惯记录一次完成的行为，把 逾期 定义为 当天结束后未打卡的状态。确认的话我现在就写进 CONTEXT.md。"

一个词被正式化，CONTEXT.md 更新。到第 5 轮，你纠结"月度报告用什么图表"——这是三分钟能拍板的事，grilling 不会为它停下来（它只推进"与实现强相关"的决策）。

最后它问："前沿已空——你确认我们已经达成共享理解？" 你确认。此刻 CONTEXT.md 已是一份干净的词汇表，docs/adr/ 躺着一份 0001-redis-async-write-persistence.md（记录"为什么先写 Redis 再异步落 MySQL"这个决策）。

第 3 步：写成规格（~10 分钟）

你：/to-spec

它不再提问，直接综合刚才的所有对话，产出 spec 并发布为本地 issue：

• Problem Statement：想养成三个核心习惯，但现有工具要么太社交化（打卡群）要么太游戏化（成就徽章），只想简单记录 + 看趋势。
• Solution：一个每天三次打卡、月底出报告的 Web 应用。
• User Stories：一长串——
• Implementation Decisions：明确写了模块划分（apps/web 打卡页、apps/api 打卡端点、lib/report 统计模块）、接口轮廓、打卡/逾期 的领域语义、Redis 异步持久化决策（引用 ADR-0001）。
• Testing Decisions：在哪个 seam 测已经议定——lib/report 的纯函数（最长 streak 计算）走单测，apps/api 的打卡端点走集成测试，apps/web 只做冒烟。
• Out of Scope：多用户、提醒推送、自定义习惯。

关键点：spec 里没有文件路径和代码片段——那些反正会过期；但 ADR 里的技术决策被引用了。

第 4 步：拆成票证

你：/to-tickets

它把 spec 拆成一组曳光弹垂直切片，每张都贯穿 API + 存储 + UI + 测试：

 01 — 创建项目骨架（Next.js + Hono + Redis 连接）   阻塞：无
 02 — 习惯定义（后端存储三个默认习惯）             阻塞：01
 03 — 打卡端点 POST /checkins + 当天补卡规则        阻塞：02
 04 — 打卡 UI（三按钮 + 当日状态）                  阻塞：03
 05 — 月度报告 API（达标天数统计）                  阻塞：03
 06 — 报告页 + streak 展示                          阻塞：04, 05
 07 — 收尾：预重构清理、README、（可选）ADR 修订   阻塞：06

它把列表给你核对："每张票都独立可演示吗？阻塞边对吗？要不要合并/拆分？"你确认后，写出 .scratch/habit-checkin/issues/01-.md … 07-.md 每个文件一张票。

第 5 步：逐张实现

你每开一个新会话就 /implement 一张票，从 01 开始：

会话 A：/implement 01 → 提交项目骨架 → /clear（丢弃这个会话）
会话 B：/implement 02 → ……

以票 03 为例，会话 B 内部会发生什么：

1. /implement 启动。
2. 它驱动 /tdd：先写一条失败测试——"同一天第二次打卡返回 already-checked-in"（红）→ 写最少实现让它绿 → 下一条。
3. 过程中你听到它说："我需要确认一个 seam：lib/report 的 streak 计算，测的是纯函数接口还是 HTTP 端点？" 你答"纯函数"——它继续。
4. 它频繁跑 typecheck 和单测；切到 API 集成测试时，启动真实 Redis（测试先用本地实例，因为 ADR-0001 说持久化路径必须真实验证）。
5. 完成时它说 "我来跑 /code-review"，然后在会话内调用它。

第 6 步：每票提交前双轴评审

/code-review（由 /implement 收尾或你手动调用），指定固定点为票 01 的提交：

• 无 hard violation。
• 一条 judgement call：lib/report/streak.ts 的 as 断言疑似 Primitive Obsession

• 01 全部满足。
• scope creep 一处：apps/api 里多了一个本票范围外的 GET /healthz 端点（无害，但不在 spec 里）。

它不合并、不排重两轴结果——你分别判断。run 07 票收尾时，顺手把 streak.ts 的类型和学生 GET /healthz 的归属问题一起处理掉。

第 7 步：收尾与持续维护

• 全部票关闭 = 主干流程走完，一个可演示的 MVP 在 main 上。
• 往后：夜间有空时 /improve-codebase-architecture 体检一次；需要给这个功能加东西时，回到 /grill-with-docs；外部用户提 bug 时走 /triage。

这个流程的关键总结

1. 先语言后代码：CONTEXT.md 和 ADR 在写第一行代码之前就存在——后续所有票证、测试名、agent 对话都用这套词汇。
2. 切片贯穿，可演示：每张票端到端可用，不产生半成品状态。
3. 每会话一张票：上下文卫生让你每张票都以"干净的窗口"开始，票证自包含。
4. 评审不代做决策：Standards 和 Spec 分开呈现，判断权在你。

这个例子里技能是随时可中断的——你可以只在某几站用（比如只有 /grill-with-docs + /implement），不会强制定流程。

---

设计哲学（理解它，改造它）

• 技能是 prompt 不是程序：每个 SKILL.md 就是结构化指令，可以直接读、改、删。
• 用户调用 vs 模型调用：disable-model-invocation: true 的只能你手动敲（如 /grill-me）；能自动触发的靠丰富的触发措辞在 agent 需要时被取用（如 /diagnosing-bugs 匹配"崩了/慢了"）。用户调用技能可调用模型调用技能，但绝不调用另一个用户调用技能。
• 约束即自我保护：diagnosing-bugs 无红循环不许猜、resolving-merge-conflicts 永不 --abort、setup-ts-deep-modules 必须演证规则咬人——防偷懒判据内置于每个流程。
• 词汇即协议：不许把 "module / interface / seam" 替换成 "component / service / boundary"——语言一致才是共享语言的意义。

---

社区与资源

• 通讯订阅（约 6 万开发者）：<https://www.aihero.dev/s/skills-newsletter>
• 技能徽章/浏览页：<https://skills.sh/mattpocock/skills>
• 仓库：<https://github.com/mattpocock/skills>
• 相关阅读：Matt Pocock 的 "smart zone"（AI 编码字典）——主干流程里上下文窗口大小的决策依据。

---

本文基于 mattpocock/skills 源码（各 SKILL.md 原文）与官方 README 整理。技能清单随仓库更新，建议以仓库为准。