22 个已发布 skill 的系统地图

1. 这节课要帮你达到什么状态

你的目标（写在 MISSION.md 里）不是「会敲 / 命令」，而是像这个仓库的作者一样思考：

• 看到一个情况，立刻知道该用哪个 skill；
• 说得出每个 skill 会动你仓库或工单系统里的哪些东西；
• 一个 skill 跑完，知道下一步该接什么；
• 某个 skill 行为不对时，知道去改哪个文件的哪一段。

这节课建立的是全局索引。索引不用硬背——后面每节深课都会回链到这里，用多了自然记住。

你的学习动机：MISSION.md · 课程安排与偏好：NOTES.md

2. 两个基本概念：什么算「已发布」、谁能启动谁

2.1 「已发布」只有一个权威

这个仓库的 skills/ 目录下躺着很多文件夹，但文件夹存在 ≠ 已经发布。 唯一说了算的清单是 .claude-plugin/plugin.json 里的 skills 数组：被它点名的 22 条路径才算发布，全部在 engineering/ 和 productivity/ 两个目录里。 misc/、personal/、in-progress/、deprecated/ 里不管有什么，都不算数，本课程也不讲。

规则原文：CLAUDE.md； 为什么用「逐条列路径」这种笨办法：ADR 0002

2.2 两种启动方式

每个 skill 都归两类之一。区别只有一个：谁能启动它。

契约全文：.agents/invocation.md · 设计词汇：writing-great-skills/GLOSSARY.md

3. 用三层来记这 22 个

22 个工具平铺着记是记不住的。作者其实是按三层组织的，像一家餐厅： 开店前先装修一次（配置层）；店长接待顾客的固定流程（编排层）； 厨师的基本功（纪律层）。

4. 主流程：一个想法从进门到交付

流程图的权威原文是 ask-matt/SKILL.md。 先用大白话把默认路线讲一遍：

1. 你有个想法，还很模糊 → 用 /grill-with-docs 让 AI 追着你面试，把想法问清楚；有代码库的话，顺手把讨论出的术语和决策写进 CONTEXT.md 和 docs/adr/。
2. 聊完发现有个问题光靠嘴说不清（状态机的手感、UI 长什么样）→ 岔出去用 /prototype 做个一次性原型，拿到答案就回来，原型代码不进正式交付。
3. 想法清楚了 → /to-spec 把它写成正式需求文档，发到工单系统。
4. 需求大到一会话做不完 → /to-tickets 拆成一张张可独立交付的工作票。
5. 每张票 → 新开一个干净会话 /implement（里面用 /tdd 写，收尾跑 /code-review，然后提交）。

改动很小的话，跳过中间所有步骤，直接 /implement 就行。

4.1 半路入口（on-ramps）

不是每个任务都从「我有个想法」开始。有三个从半路并入主流程的入口：

• /triage：别人在你的工单系统提了一堆 bug 和需求，你先拿它分拣（贴标签、写处理意见）；分拣完、标了 ready-for-agent 的 issue 直接进 /implement。
• /diagnosing-bugs：遇到难缠的 bug 用它建立「必现失败」的反馈环做诊断；修完发现根子是架构问题，转去 /improve-codebase-architecture。
• /wayfinder：任务大到或模糊到一个会话装不下时，先不交付，画一张「决策地图」——把要回答的问题列成工单逐个解决；疑问清空后去 /to-spec 走主流程，不要跳过 spec 直接 implement。

主流程之外还有三类常驻角色：

• 词汇地板：/domain-modeling 和 /codebase-design 不在主流程上，但主流程的每一步都可能调用它们（一个管领域术语，一个管模块设计的词汇）。
• 架构保养：/improve-codebase-architecture 给代码库做体检，产出的改进想法再进 /grill-with-docs 走主流程。
• 跨会话桥：/handoff 把讨论移交到一个新会话；harness 自带的 /compact 是同一窗口内压缩。两者不一样——换窗口用 handoff。

4.2 上下文卫生（context hygiene）

「上下文」就是 AI 在一个会话里能看到的全部内容。窗口是有限的，塞得太满，推理质量就下降。 作者因此定了几条硬规矩，叫 context hygiene：

• grill → spec → tickets 尽量在同一个会话里一气呵成，中途不要 compact，让这三步共享同一套推理。
• 每次 /implement 新开一个会话，只带那一张票进去——别拖着之前聊了几万字的旧上下文。
• 感觉会话逼近 smart zone（大约 120k token 之后推理质量开始下滑的区间）时，用 /handoff 移交新会话，别硬撑。
• /to-tickets 拆出来的票不要再拿 /triage 分拣一遍——它们生来就是可以直接交给 agent 做的；triage 只处理别人提的、你没写过的外来 issue。

smart zone 词条（ask-matt 外链）： aihero.dev/ai-coding-dictionary/smart-zone

5. 全表：22 个 skill 逐个看

这是全课程信息量最大的一节。reference/ 里有对应的速查表，值得打印。 「会改什么」= 按各 skill 的 SKILL.md 承诺会留下的痕迹（文件、工单、git 提交、临时目录）； 只在对话里推理、不写任何文件的，标「不留痕迹」。

5.1 Engineering · 只能人启动

5.2 Engineering · 人和 AI 都能启动

5.3 Productivity

给人看的叙事版文档（不是 agent 的行为真源）： https://aihero.dev/skills-<name>，仓库内镜像在 docs/engineering/、docs/productivity/。

6. 反着查：仓库里多了个东西，是谁干的

遇到「仓库里怎么突然多了个文件 / 评论」时，从产物反查作者，比按 skill 名单逐个扫更快。

术语：CONTEXT.md（Issue tracker / Decision ticket / Triage role）

7. skill 之间怎么互相调用（五条规则）

1. 依赖用「一句话」表达：正文里写 Run the /grilling skill 这种自然语言调用；禁止用 ../other/SKILL.md 这种跨目录深链来共享逻辑（invocation.md 的 Dependencies 规则）。
2. 共享词汇集中放：domain-modeling、codebase-design、grilling 是「地板」——任何上层 skill 需要时就调用它们，而不是把同样的规则抄进自己的正文。
3. 入口薄、纪律厚：grill-me / grill-with-docs / implement 故意写得极短。想改行为时，先打开被它们调用的那个厚文件。
4. 配置先于工单写入：to-spec / to-tickets / triage / wayfinder / code-review 都假定 setup 跑过；没跑过，它们会让你先去 setup。
5. 路由器不替你干活：ask-matt 只负责指向某个 user-invoked skill；真正启动，仍需你亲手输入那个名字。

grill-me            → grilling
grill-with-docs     → grilling + domain-modeling
implement           → tdd … 然后 code-review … 然后 commit
triage（需要时）     → grilling + domain-modeling
wayfinder 画图       → grilling + domain-modeling；研究票 → research
wayfinder 做票       → 按票的类型走（research | prototype | grilling | task）
improve-arch        → codebase-design；选定后 grilling + domain-modeling
diagnosing-bugs     → （可选）improve-codebase-architecture

8. 什么时候可以故意跳步

地图给的是默认路线，不是宗教仪式。所谓灵活运用 = 知道每条默认规则为什么存在，然后有意识地偏离它。

9. 检索练习

先别往回翻表，凭记忆答。选项字数刻意对齐，不会从长度泄题。

10. 下一课与一手材料

本课主一手材料（请打开原文读，不要只背本页摘要）：

• skills/engineering/ask-matt/SKILL.md —— 流程图的权威原文，读全文（主流程、半路入口、上下文卫生、独立技能）。
• .agents/invocation.md —— 两种启动方式的契约，以及「prose 调用、user 不能调 user」。
• .claude-plugin/plugin.json —— 对照第 5 节的表，数数是不是正好 22 条路径。

建议下一课（0002）： setup-matt-pocock-skills——配置层唯一的 skill。没有它， to-spec / to-tickets / triage / wayfinder 的「会改什么」全都落在一个没定义过的工单系统上。 深课会逐段对照它的「探索 → 提问 → 确认 → 写入」流程，以及它生成的 docs/agents/* 模板里每个字段的含义。