Lesson 0019 · Engineering · 只能人启动（user-invoked）· 地图课

ask-matt：整套 skill 的路由器

你刚装完 22 个 skill，新会话打开，光标在闪。手里有个模糊的想法， 或者一堆别人提的 bug，你盯着输入框想的第一个问题是：我现在该敲哪个斜杠命令？ ask-matt 就是为这个瞬间准备的：你用大白话描述处境，它告诉你该走哪条 flow（流程：一条穿过多个 skill 的路线）、从哪一步进、按什么顺序跑。 它自己什么都不干——不面试你、不写需求文档、不改代码，只负责指路。 学完这节课，你能默写出它的整张地图（一条主流程、三条半路入口、五个独立工具、两块词汇地板）， 知道每条路之间在哪里并线，也知道当地图和现实脱节时，该去改哪个文件的哪一段。

1. 它在整个系统里站在哪

0001 把 22 个已发布 skill 分成三层：配置层（setup-matt-pocock-skills，跑一次性的初始设置）、 编排层（你手动启动的完整流程）、纪律层（被反复调用的基本功）。 ask-matt 在编排层里，但它是编排层里的一个异类：别的编排层 skill 各自负责一条流程， 而 ask-matt 不负责任何一条流程，它负责所有流程之间的地图。 文档的原话是：它是「a router over the skills in this repo」（覆盖本仓库全部 skill 的一台路由器）。

它存在的理由，文档也说得很直白：这套系统里有一大半 skill 是只能人启动的（user-invoked）， 没有任何机制替你触发它们——你必须自己记得它们存在、记得各自管什么。 22 个名字谁都记不全，于是作者把这份记忆外包给了一个 skill： SKILL.md 开篇第一句就是「You don't remember every skill, so ask.」（你记不住所有 skill，所以问。） 文档的说法是：ask-matt is the memory you offload that to（ask-matt 就是你卸下这份记忆的地方）。

还有两个定位事实值得记住。第一，0001 讲过：全系统流程图的权威原文就是 ask-matt/SKILL.md——0001 那张主流程图是照着它画的，不是反过来。 第二，文档把它描述为「the node every other docs page links back to」（其它每个文档页都回链到它的节点）： 它从不坐在任何一条链子里，而是指向每一条链子 （it never sits in a chain; it points into every chain）。 所以它没有一个「上游 skill」或「下游 skill」——它的邻居是所有 skill。

这也带来一条维护义务。仓库根目录的 AGENTS.md 规定： 每当你新增、改名、删除一个 user-reachable skill，或改变它在流程里的位置， 都必须重读 ask-matt 的 SKILL.md 并同步更新—— 原文的警告是：「a new skill it never mentions, or a stale one it still routes to, is a router that lies」 （一个它从不提及的新 skill，或一个它还在指路的过时 skill，就是一台说谎的路由器）。 这节课本身就是这条规则的产物：你在学的这张地图，必须和仓库里 22 个 skill 的实际状态一一对应。

罗盘：MISSION.md · 地图总览：0001 系统地图 · 权威原文：ask-matt/SKILL.md · 叙事版：docs/engineering/ask-matt.md · 同步义务：AGENTS.md

2. 调用方式与触发场景

2.1 只能人启动，AI 永远不会自己加载它

ask-matt 是 user-invoked（只能人启动）的。这个事实写在两个地方，两道锁：

• SKILL.md 的 frontmatter 里有一行 disable-model-invocation: true—— 禁止模型（AI）主动调用这个 skill。
• 同目录下的 agents/openai.yaml 里有 policy.allow_implicit_invocation: false—— 在 OpenAI 系的 harness 里同样禁止隐式（未经你点名的）调用。

文档把话说得很死：「You invoke this by typing /ask-matt — the agent won't reach for it on its own.」 （你通过输入 /ask-matt 来调用它——agent 不会自己伸手拿它。） 这很合理：一台路由器如果会被 AI 在后台随手加载，就失去了「你主动求助」这个语义。 它的 frontmatter description（描述字段）写的是 「Ask which skill or flow fits your situation. A router over the skills in this repo.」—— 注意，对 user-invoked skill 来说，这段描述不是给 AI 的触发条件，而是给你看的功能摘要； 真正决定「AI 会不会自己用它」的是上面那两行配置。

2.2 什么时候该问它，什么时候别绕路

两道锁： ask-matt/SKILL.md 的 frontmatter · ask-matt/agents/openai.yaml · 触发场景： docs/engineering/ask-matt.md 的「When to reach for it」一节

3. 路由器自己的词汇

ask-matt 不是词汇地板 skill（那是 domain-modeling 和 codebase-design 的角色）， 但它有一小套自己的结构性词汇，整张地图都是用这些词画的。 这些词在 SKILL.md 里以小节标题和加粗词的形式出现，下面按原文压缩成表。 第一次读可以慢一点——后面每一节都在用这些词。

地图上还会碰到几个来自 CONTEXT.md 的领域词和来自其它 skill 的术语，先在这里钉住， 后面不再重复解释：

• Issue tracker（工单系统）：托管一个仓库全部 issue 的工具——GitHub Issues、Linear， 或本地一套 .scratch/ 目录下的 markdown 约定。
• Issue：工单系统里一个被跟踪的工作单元——一个 bug、一项任务、一份需求、 或 to-tickets 拆出来的一片交付。
• Decision ticket（决策票）：wayfinder 专用的一种 issue—— 挂在 wayfinder:map 父 issue 下的子 issue，装的是一个问题， 它的「解决」意味着做出一个决策，而不是交付一片代码。
• Triage role（分拣角色）：分拣过程中贴在一个 issue 上的状态机标签 （比如 needs-triage、ready-for-afk），每个角色对应工单系统里一个真实标签字符串。
• Tracer-bullet ticket（曳光弹式工作票）：to-tickets 拆出来的票， 每张都是端到端能跑通的一小片（像曳光弹一样从枪膛直穿到目标），而不是「先做完整层数据库再做完整层 UI」的水平切片。
• Blocking edge（阻塞边）：票与票之间声明的依赖关系——「这张票被那张票挡住」。 本地工单系统里它是一句文字声明，远程工单系统里它变成原生的阻塞链接。
• Agent-ready：一张 issue 已经达到「可以直接丢给 agent 做」的成熟状态—— 问题清楚、范围清楚、用词符合项目术语表。
• Smart zone（聪明区）：模型仍然推理敏锐的那段上下文窗口 （在最先进的模型上大约是 12 万 token 以内）。超出它，推理质量开始下滑。

结构词汇：ask-matt/SKILL.md 各小节标题 · 领域词：CONTEXT.md · smart zone 词条：aihero.dev/ai-coding-dictionary/smart-zone

4. 主流程逐步拆解：idea → ship

SKILL.md 对主流程的介绍只有一句话：「The route most work travels. You have an idea and want it built.」 （多数工作走的路线。你有个想法，想把它做出来。）下面按原文的三步加一个分支结构拆开讲， 每一步都标出它点名的 skill 和对应的课。

4.1 第 1 步：/grill-with-docs —— 用面试把想法磨清楚

主流程从/grill-with-docs开始：有代码库就从这里开始。 它是「有状态的」（stateful）——面试过程中学到的东西会留在 CONTEXT.md 和 ADR（架构决策记录）里，成为仓库的永久资产。没有代码库就改用 /grill-me（见第 7 节的独立工具）。两者跑的是同一个底层纪律 /grilling（面试基本功），区别只在 grill-with-docs 会留下书面记录 （paper trail）。

4.2 第一个分支：所有问题都能在对话里解决吗

面试过程中如果冒出一个问题，光靠嘴说不清——涉及状态机的手感、业务逻辑的实际行为、 一个必须亲眼看到的 UI——主流程允许你岔出去做一次原型， 来回都靠 /handoff 搭桥：

1. /handoff 把当前对话压成一个 markdown 文件，岔出去；
2. 拿着那个文件新开一个会话，在里面跑 /prototype，用一次性代码回答那个问题；
3. 再 /handoff 把学到的东西带回来，在原来的想法线程里引用它。

注意这个岔路是「双向桥」：出去一次 handoff，回来再一次 handoff。原型代码本身是消耗品， 答案才是要带回主流程的东西（prototype 的纪律是「留住答案，删掉代码」，见 0008）。

4.3 第二个分支：这是多会话的大活吗

无论走哪个分支，/implement 的内部都是同一套纪律： 它驱动 /tdd 一次做一片红绿循环（red-green slice：先写一个失败测试，再写实现让它通过）， 收尾时跑 /code-review——一场沿两条轴的 diff 审查（Standards 轴查编码规范，Spec 轴查是否符合需求）， 审完才提交（commit）。

SKILL.md 还特意给 tdd 和 code-review 留了两个「单用」出口： 只想先测试先行地做一个小行为、不想要完整需求文档 → 单独用 /tdd； 想拿一个分支或 PR 对着某个固定点审一遍 → 单独用 /code-review。 这两个 skill 虽然是 model-invoked 的纪律层成员，但人也可以点名启动。

你的想法
  │
  ▼
/grill-with-docs ──── 没代码库？ → /grill-me（不留记录）
  │
  ├─ 有问题嘴说不清？ ─ /handoff ─→（新会话）/prototype ─ /handoff ─→ 带回答案
  │
  ▼
多会话大活？
  ├─ 是 ─ /to-spec ─ /to-tickets ─（每张票清上下文）─ /implement × N
  │                                              │  内部驱动 /tdd
  └─ 否 ─ 直接 /implement ───────────────────────┤  收尾 /code-review
                                                 ▼
                                              commit

权威原文：ask-matt/SKILL.md 的「The main flow」一节 · 各站课程： 0003 grilling · 0006 handoff · 0008 prototype · 0009 to-spec · 0010 to-tickets · 0011 implement · 0012 tdd · 0013 code-review

5. 上下文卫生与 smart zone

主流程一节里夹着一段 Context hygiene（上下文卫生），它是整张地图上少有的 「纪律性」文字，值得单独一节。「上下文」指 AI 在一个会话里能看到的全部内容；窗口有限， 塞得太满，推理质量就下滑。原文定了几条硬规矩：

1. 第 1 到第 3 步（grill → spec → tickets）放在同一个不中断的上下文窗口里—— 在 /to-tickets 跑完之前，不要 compact、不要清上下文。 理由：面试、需求文档、拆票这三件事是在同一套思考上层层累积的，中间断一次， 后面两步就站在残缺的推理上。
2. 每次 /implement 都新开一个干净会话，只带那一张票进去—— 别拖着之前聊了几万字的旧上下文。
3. 盯着 smart zone：如果会话在 /to-tickets 之前就逼近聪明区上限， 不要顶着下滑的推理质量硬撑——用 /handoff 移交，在新线程里继续。 原文的措辞是「don't push on degraded」（别在降级状态下硬推）。

权威原文：ask-matt/SKILL.md 的「Context hygiene」一段 · smart zone 词条：aihero.dev/ai-coding-dictionary/smart-zone · 0001 的转述：0001 系统地图第 4.2 节

6. 三条半路入口与代码库保养

不是每份工作都从「我有个想法」开始。bug 是别人报的、故障是半夜冒出来的、大项目是雾做成的—— 这些处境各自有一条匝道，把工作产生出来、再并上主流程。

6.1 /triage —— 别人提的工作堆起来了

处境：工单系统里堆着别人报的 bug 和需求。/triage 把 issue 挨个推过分拣角色 （triage role，状态机标签），产出 agent-ready 的 issue， 之后由 /implement 认领。

6.2 /diagnosing-bugs —— 有东西坏了，而且不好修

处境：有难缠的 bug——第一眼看不透的那种、间歇性发作的 flake、在两个已知良好状态之间 悄悄溜进来的回归。/diagnosing-bugs 的纪律是：在没有拿到一个 紧密反馈环（tight feedback loop：一条已经能因为这个 bug 变红的命令）之前，拒绝做任何推测； 修复时必须带上回归测试。它的复盘（post-mortem）环节有一个出口：当真正的发现是 「代码里没有一条好接缝能锁住这个 bug」时，移交给 /improve-codebase-architecture。

6.3 /wayfinder —— 大到、模糊到一个会话装不下的活

处境：一片巨大的、雾蒙蒙的工程——绿地项目（greenfield，从零开始的项目）或超大功能， 从这里到目的地的路还看不见。/wayfinder 是全系统认知负荷最高的一条流程： 它在工单系统上画一张共享地图——一个 wayfinder:map 父 issue 挂着若干决策票——然后一次解决一张，产出的是决策，不是交付物， 直到雾被推回去、路看清为止。

雾散之后，原文用了加粗的四个字：它移交，不建造（it hands off, it doesn't build）。 默认在 /to-spec 并上主流程——to-spec 会把地图上链好的决策 坍缩成一份可建造的计划，然后照常 /to-tickets、/implement。 把地图直接捅进 /implement 会跳过这次坍缩、把链好的细节全部扔掉—— 只有当工程量最后证明真的很小时，才允许直接进 /implement。

6.4 Codebase health：/improve-codebase-architecture

这一格不是功能开发，是保养。/improve-codebase-architecture 的建议使用频率是 「一有空就跑」（whenever you have a spare moment），目标是让代码库始终保持「对 agent 友好」。 它扫描出加深机会（deepening opportunity：把浅模块加深的重构候选）； 你挑中一个，就产生了一个新想法，可以拿进主流程的 /grill-with-docs。 原文给了一个很顺手的比喻：它是「找到候选的勘察」（survey）， /codebase-design 是「设计那个入选候选的工作台」（bench）—— 勘察找出值得加工的石头，工作台负责加工。

权威原文：ask-matt/SKILL.md 的「On-ramps」和「Codebase health」两节 · 各站课程： 0014 triage · 0015 diagnosing-bugs · 0016 wayfinder · 0017 improve-codebase-architecture · 0005 codebase-design

7. 五个独立工具与跨会话

Standalone（独立工具）完全不在主流程上——想用就直接拿，没有前置步骤。 地图上列了五个，外加一对跨会话手段。

7.1 /handoff vs /compact：换窗口，还是不换

「跨会话」一节把两个容易混淆的手段并排钉死：

7.2 一个不在这张地图上的 skill

诚实地指出一个观察：resolving-merge-conflicts（解合并冲突）出现在 0001 的纪律层名单里， 但没有出现在 ask-matt 的地图上——它的 SKILL.md 通篇没有给它格子。 这和文档的自我描述一致：ask-matt 除了 user-invoked skill 之外，只点名「你会按名字够到的」 那几个 model-invoked skill（tdd、diagnosing-bugs、prototype、code-review 和两块词汇地板）， 并不追求罗列全部 22 个。解冲突这种「在 implement 途中撞见、由纪律层接管」的基本功， 不是你会站在路口问「我该不该用它」的东西——撞见冲突的那一刻，答案已经写脸上了。 读这张地图时记住：它是路由指南，不是完整名册；完整名册在 0001 和 .claude-plugin/plugin.json。

权威原文：ask-matt/SKILL.md 的「Standalone」和「Crossing sessions」两节 · 文档自述点名范围：docs/engineering/ask-matt.md · 名册：0001 系统地图 · 冲突一课：0018 resolving-merge-conflicts

8. 副作用、依赖关系、地图对照表

8.1 会留下什么：什么都不留

0001 的全表对 ask-matt 的「会改什么」一栏写的是：什么都不改，只在对话里指路。 不写仓库里的文件，不动工单系统，不产生 git 提交，不写临时目录。 它是 22 个 skill 里最「干净」的一个——跑一百次 ask-matt，仓库的 diff 依然是空的。 这也符合路由器的本分：它回答「which one, and when」，真正的痕迹由它指到的那个 skill 留下。

8.2 依赖谁、被谁依赖

• 它依赖所有它指路的 skill——不是代码上的依赖，是事实上的依赖： 地图上每一句话都是对其余 21 个 skill「存在且行为如此」的断言。任何断言过时，地图就开始说谎 （AGENTS.md 的「router that lies」警告）。
• 没有任何 skill 依赖它——它从不坐在任何一条链子里。没有流程会先跑 ask-matt 再跑别的；它是给人用的地图，不是机器用的中间件。
• 文档侧的反向链接：docs 页说自己是「the node every other docs page links back to」—— 每个 skill 的人读文档都会指回这台路由器；当地图自己都过时了， 「its Source is the map of record」（以源码仓库为权威地图）。

8.3 地图对照表：每个被点名的 skill 对应哪节课

这张表是 ask-matt 地图和整套课程的索引。路由器说「去 X」，你就去 X 的课深读。

8.4 用完之后，下一步去哪

1. 拿到指路了 → 亲手输入它点名的那个 skill。路由器不替你按回车。
2. 它把你放到主流程某一步 → 按第 5 节的上下文卫生安排窗口：grill/spec/tickets 同一窗口，implement 每票新窗口。
3. 它把你放到 on-ramp → 记住并线点：triage 出 agent-ready 的 issue 给 implement；diagnosing-bugs 的复盘可移交 architecture；wayfinder 雾散后默认去 to-spec。
4. 已经知道答案 → 下次直接调目标 skill，别绕路由器。

副作用一栏：0001 系统地图第 5.1 节 · 「只定向不执行」：docs/engineering/ask-matt.md

9. 行为不对时改哪里

路由器「行为不对」只有一种形态：指路指错了，或者指路过时了。 因为它没有任何执行逻辑，微调入口也只有一个文件的几段文字。

10. 检索练习

先别往回翻，凭记忆答。选项长度刻意对齐，不会从版式泄题。答错的题回到对应小节核对原文。

11. 下一课与一手材料

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

• skills/engineering/ask-matt/SKILL.md —— 整张地图的权威原文：主流程、上下文卫生、on-ramps、codebase health、词汇地板、跨会话、standalone、前置条件。
• skills/engineering/ask-matt/agents/openai.yaml —— 调用锁的第二道：allow_implicit_invocation: false。
• docs/engineering/ask-matt.md —— 给人看的叙事版：「它不干活，只定向」「flow 而不是单个 skill」。 （线上版：aihero.dev/skills-ask-matt）
• AGENTS.md —— 「router that lies」同步义务的出处：改任何 user-reachable skill，就要回来改这张地图。
• CONTEXT.md —— Issue tracker / Issue / Decision ticket / Triage role 四个领域词的唯一定义。
• 地图对照： 0001 系统地图（22 个 skill 的全表与三层结构）。

速查页（本课同步）： reference/ask-matt.html

导航： 上一课 0018 resolving-merge-conflicts （不在 ask-matt 地图上的那个纪律层 skill）。 总览仍回 0001 系统地图。

建议下一课（0020）： 0020 writing-great-skills —— 你已经会把这套系统当用户用了：知道每条路通到哪、每个 skill 留什么痕迹。 下一课换一个身份：当作者——怎么写出和这 22 个一样好的 skill， 以及写完怎么让 ask-matt 这张地图把你收录进去（还记得「router that lies」吗）。