先上手：装在哪、第一次跑什么
装在哪。 用户级放 ~/.pi/agent/skills/ 或 ~/.agents/skills/，项目级放 .agents/skills/。Claude Code 放 ~/.claude/skills/。带 SKILL.md 的目录会被递归发现，改完不用重启。
会不会乱插话。 不会。自动的 11 个只在触发词命中时加载，手动的你不打就不跑。自动的也能主动点名，打 /tdd 一样有效。
第一次只做三步。 /grill-with-docs → /implement → /retro。跑顺了再开 to-spec / to-tickets 那套多 session 编排。
什么时候别用。 改 typo、写一次性脚本、改配置，直接让它写，别开流程。
主流程：idea → ship → retro
官方主线路（源自 ask-matt）：磨想法 →（纸上定不下来绕原型）→（多 session 才落 spec 拆 ticket）→ 实现 → 评审 → 提 PR → 复盘。六步，分支按场景选。
磨想法（必经）
| 场景 | Skill |
|---|---|
| 有工作目录 → 首选起点，边问边落 GLOSSARY.md / ADR | 🟨 grill-with-docs |
| 无仓库 / 不落盘 → 纯磨方案 | 🟨 grill-me 或 🟦 grilling |
grilling 是逐问审讯的底层原语：grill-me / grill-with-docs 是它的两个包装，triage / wayfinder / improve-codebase-architecture 内部也跑它。
绕原型（分支 A：对话里敲不定时）
状态模型对不对 / UI 长什么样 → 一次性原型给答案：
🟨 handoff（出，存 %TEMP%）→ 🟦 prototype → 🟨 handoff（回原线程）
原型验证后主干只留决策；原型本身 commit 到 prototype/<name> 分支当一手源。
落 spec 拆 ticket（分支 B：多 session 大项目）
- 🟨
to-spec — 把当前对话压成 spec 发布 tracker，标 ready-for-agent - 🟨
to-tickets — spec 拆成 tracer-bullet ticket：每片垂直切穿所有层、独立可演示、一个新窗口装得下，每张声明阻塞边；宽改走 expand–contract 三段式
小功能直接跳到「实现」那一步。
⚠ 上下文纪律：从 grilling 到 to-tickets 保持同一个不间断窗口，让磨、spec、ticket 建立在同一路思考上。
实现（核心）
所有路径最终都由 🟦 tdd 驱动（红绿重构，垂直切片，在 spec 阶段约好的 seam 处调用）。拿到什么决定驱动方式：
| 拿到什么 | 驱动方式 |
|---|---|
| 一个功能点 / 一个 bug | 🟦 tdd 裸用，只管"写"，收尾自己做 |
| 一张 ticket | 🟨 implement 单票闭环：取票→tdd→类型检查/测试→code-review→commit；ticket 间 /clear |
| 一整份 spec | 🟨 implement-spec：ticket 当任务图，就绪 frontier 上并行跑 implementer 子代理（各自 worktree），merger 合并到集成分支，收尾一次整体 review |
评审与提交（收尾）
- 🟦
code-review — 对固定点以来的 diff 双轴评审：Standards（本仓规范 + Fowler 坏味道基线）与 Spec（符不符原始需求），双子代理并行。implement / implement-spec 已内含 - 🟦
pr — PR body 三段式：最小可视化 Summary + 前后证据 Evidence + 合并风险 Merge Danger（单向/双向门）
复盘（闭环）
🟨 retro — 复盘本 session，改进的是 agent 的环境而非代码：导航指针 / 自动化检查 / 编码规范 / steering 文件 / 工具经济性，按严重度出建议。机械错误→确定性检查（linter/hook/CI），判断题→编码规范。
尤其 bug 修完之后跑一次 retro；修 bug 时没好 seam 锁回归测试 → 交给 improve-codebase-architecture。
三条推荐链路
| 规模 | 链路 | 说明 |
|---|---|---|
| 轻 · 80% 日常 | tdd → code-review → commit | 一个功能点/一个 bug，自动触发，无编排开销 |
| 中 · 单 session 功能 | grill-with-docs → implement → pr → retro | 一个窗口装得下；implement 内含 tdd + code-review + commit |
| 重 · 多 session 项目 | grill-with-docs → to-spec → to-tickets → implement-spec → retro | 任务图 + 并行子代理；想亲自逐张驱动就 implement ×N（张间 /clear） |
入口：遇到什么事，从哪进
| 遇到什么 | 怎么入手 | Skill |
|---|---|---|
| 我有个想法，细节没敲定 | 仓库里 → grill-with-docs（首选，留纸带）；无仓库 → grill-me | 🟨 grill-with-docs / grill-me |
| 东西坏了 / 变慢 / 抛异常 | 先建"一条命令就能红"的反馈环，再假设→插桩→修→回归测试；修完同 session 跑 retro | 🟦 diagnosing-bugs → 🟨 retro |
| 别人提的 issue / PR 堆积了 | triage 状态机分拣：分类（bug/enhancement）+ 状态五角色，产 agent-ready brief，之后 implement 认领。⚠ to-tickets 产的票已 ready，不要再 triage | 🟨 triage → implement |
| 项目大到没方向，一个 session 装不下 | wayfinder 把雾画成决策 ticket 地图，逐张解决，产出决策而非交付物；图清了在 to-spec 汇入主线（不要直跳 implement） | 🟨 wayfinder → to-spec |
| 要查技术事实，但不想停下手里活 | 后台 agent 对一手源调研，落带引用 markdown 进仓；笔记稍后带进 grill-with-docs | 🟦 research |
| 决定卡在别人脑子里 | to-questionnaire 反向磨"发送"：问你要发给谁、要回什么，产出问卷给对方填；答案回来喂 grill-with-docs / to-spec | 🟨 to-questionnaire |
| 只有人能做的步骤（开权限/配密钥/点后台） | 生成交互式 bash 向导：打开每个 URL、抓每个值、写进 .env | 🟦 wizard |
| 没听懂 agent 刚说的话 | 立刻喊停：用 GLOSSARY.md 词汇 + 简明技术英语重讲；任何 skill 中途都能用 | 🟨 wait-what |
| 不知道该用哪个 skill | 问路由器，它会读完候选 skill 的 SKILL.md 再回答 | 🟨 ask-matt |
长期使用：知识怎么沉淀
这套 skill 的长期价值在留痕：每条链路都有对应的落盘产物，下次 session（或下一个 agent）从纸带上接力，而不是从零开始。
| 沉淀什么 | 落盘产物 | Skill |
|---|---|---|
| 术语与决策（最核心） | GLOSSARY.md（术语表）+ docs/adr/（难回头的决策）。边讨论边写，写 spec、起 issue、写测试名都用 glossary 的词，不许漂移到 Avoid 同义词 | 🟨 grill-with-docs 🟦 domain-modeling |
| 规划痕迹 | .scratch/<feature>/spec.md、.scratch/<feature>/issues/NN-*.md（带 Blocked by 边）、.scratch/<effort>/map.md（wayfinder 地图） | 🟨 to-spec to-tickets wayfinder |
| 研究与原型 | research 落带引用 markdown；prototype 验证后主干只留决策，原型 commit 到 prototype/<name> 分支当一手源，实现 issue 上留指针 | 🟦 research prototype |
| 环境进化 | 每次 build 收尾跑 retro：机械错误变成确定性检查，判断题写进编码规范给 reviewer agent。代码库随使用越来越好开 | 🟨 retro |
| 代码库保养 | improve-codebase-architecture 扫描深化机会出 HTML 报告，选中一项产生一个"想法"带进主线磨；codebase-design 是设计时的深模块词汇 | 🟨 improve-codebase-architecture 🟦 codebase-design |
| 窗口接力 | smart zone 约 150k token，逼近就在阶段边界处理：continue / handoff（换 harness、目录、同事时，落 %TEMP% 便携 md）/ subagent / /clear。handoff 不重复已落盘内容，只留指针 | 🟨 handoff |
| 学习与元技能 | teach 跨多 session 学概念（当前目录做教学工作区）；writing-for-agents 是写 skill / AGENTS.md / 指针文档的风格规范 | 🟨 teach 🟦 writing-for-agents |
| 前置配置（本仓已完成） | docs/agents/*.md：issue tracker（本仓 .scratch/ 本地 markdown）、triage 标签、GLOSSARY 布局 | 🟨 setup-matt-pocock-skills |
易混 skill 对比
implement vs implement-spec vs 裸 tdd
三者都是"写代码"，区别在输入规模和编排方式。tdd 是引擎，implement 是单票闭环，implement-spec 是整 spec 编排。
| 🟦 tdd | 🟨 implement | 🟨 implement-spec | |
|---|---|---|---|
| 输入 | 一个功能点 / bug | 一张 ticket | 一整份 spec + 任务图 |
| 执行 | 本窗口 | 本窗口，ticket 间 /clear | 子代理并行跑就绪 frontier，各自 worktree |
| review | 不含，自己补 | 每张内含 code-review | 集成分支一次整体 review |
| commit | 不含 | 含，提交到当前分支 | 含，统一落集成分支 |
grilling vs grill-me vs grill-with-docs
同一套逐问审讯的三个形态：原语、无状态包装、有状态包装。
| 🟦 grilling | 🟨 grill-me | 🟨 grill-with-docs | |
|---|---|---|---|
| 定位 | 原语，无包装 | 无状态包装 | 有状态包装 |
| 落盘 | 不落 | 不落任何东西 | 落 GLOSSARY.md + ADR |
| 何时用 | 只要审讯本身 | 无仓库 / 纯磨方案 | 有仓库（严格更优，留纸带） |
另外 triage / wayfinder / improve-codebase-architecture 内部都跑 grilling——你在这些流程里被追问是正常的。
to-spec vs to-tickets vs wayfinder
规划三件套，粒度递增：一次对话的沉淀 → 一份 spec 的拆解 → 一片雾的地图。
| 🟨 to-spec | 🟨 to-tickets | 🟨 wayfinder | |
|---|---|---|---|
| 输入 | 当前对话 | spec / 计划 / 对话 | 一个装不下的大方向 |
| 产出 | spec.md 发布 tracker | 带阻塞边的 tracer-bullet 票 | 决策 ticket 地图 + 逐张解决 |
| 回答 | 做什么、为什么 | 按什么顺序做 | 路在哪（决策，非交付物） |
| 下游 | to-tickets | implement / implement-spec | to-spec 汇入主线 |
handoff vs to-questionnaire
都是"知识缺口"问题，但缺口位置不同：一个在你自己的窗口里，一个在别人的脑子里。
| 🟨 handoff | 🟨 to-questionnaire | |
|---|---|---|
| 缺口 | 新窗口没有旧上下文 | 你缺的知识在别人那里 |
| 动作 | 压缩对话成便携 md | 生成问卷让对方填 |
| 审讯对象 | 不审，只综合 | 磨"发送"：给谁、要回什么 |
| 产物 | %TEMP% 下的 handoff 文档 | to-questionnaire-<slug>.md |
code-review vs improve-codebase-architecture vs retro
三个"回头看"，看的对象不同：看 diff、看结构、看 session。
| 🟦 code-review | 🟨 improve-codebase-arch | 🟨 retro | |
|---|---|---|---|
| 看什么 | 固定点以来的 diff | 整个代码库的结构 | 刚过去的 session |
| 输出 | Standards + Spec 双轴报告 | 深化机会 HTML 报告 | 环境改进建议（按严重度） |
| 改代码 | 不改 | 不改，选中项再带进主线磨 | 不改代码，改环境 |
| 时机 | 每次提交前 | 有空的时候 | build 后 / 修完 bug 后、/clear 前 |
wait-what vs grilling
都关于"沟通不畅"，一个事后纠偏，一个事前磨刀。
| 🟨 wait-what | 🟦 grilling / grill-with-docs | |
|---|---|---|
| 时机 | 事中/事后：刚没听懂 | 事前：动手之前 |
| 方向 | agent 向你重讲（用 GLOSSARY 词） | agent 逐问你，敲定设计 |
| 根治 | 对症下药 | 提前共享语言，让 jargon 根本不出现 |
自动调用 vs 手动触发 · 全表
🟦 自动 · 模型按触发词调用（11 个）
正常干活时模型自己会伸手。没触发就：换触发词 → 点名 skill → 给路径读 SKILL.md。
| Skill | 干什么 | 触发词 |
|---|---|---|
grilling | 逐问审讯原语，grilling 系和 triage/wayfinder 的底层引擎 | stress-test / grill |
tdd | 红绿重构，垂直切片，所有实现路径的写码引擎 | test-first / red-green |
code-review | diff 双轴评审：本仓规范 + 原始需求，双子代理并行 | review since X / 评审分支 |
pr | PR body 三段式：Summary + Evidence + Merge Danger | 写 PR body 时 |
diagnosing-bugs | 难 bug / 性能回归：先建反馈环再假设修复 | 坏了 / 慢 / 抛异常 / diagnose |
prototype | 一次性原型：逻辑出 HTML 演示，UI 出多方案切换 | 验证设计 / 看效果 |
research | 后台 agent 对一手源调研，落带引用 markdown | 调研 / 查 API / 查文档 |
domain-modeling | 术语结晶落 GLOSSARY.md，难回头的决策记 ADR | 术语 / GLOSSARY / ADR |
codebase-design | 深模块设计词汇：接口小、seam 干净、可测 | 模块接口 / seam / 深化 |
wizard | 只有人能做的步骤生成交互式 bash 向导 | 配密钥 / 点后台 / 开权限 |
writing-for-agents | 写 agent 消费的文档（skill/AGENTS.md/指针文档）的风格规范 | 写 skill / 改 AGENTS.md |
🟨 手动 · 只有你显式发起（16 个）
多为流程编排与入口类。想不起用哪个 → /ask-matt。
| Skill | 干什么 |
|---|---|
ask-matt | 路由器：不知道用哪个 skill/flow 时问它 |
grill-with-docs | 有仓库的首选磨方案入口，边问边落 GLOSSARY/ADR |
grill-me | 无仓库版纯磨方案，不落盘 |
triage | 外部 issue/PR 走状态机分拣，产 agent-ready brief |
to-spec | 当前对话压成 spec 发布 tracker |
to-tickets | spec 拆带阻塞边的 tracer-bullet 票 |
implement | 单 ticket 完整闭环：tdd→测试→review→commit |
implement-spec | 整 spec 一条集成分支：任务图 + 并行子代理 |
wayfinder | 装不下的大项目画决策地图，逐张拨雾 |
improve-codebase-architecture | 扫描深化机会出 HTML 报告，选中项带进主线磨 |
retro | 复盘 session，改进 agent 环境（检查/规范/导航） |
handoff | 压缩对话成便携 md，供新窗口/同事接力 |
to-questionnaire | 决定卡在别人脑子里 → 生成问卷给对方填 |
wait-what | 没听懂刚的话 → 用 GLOSSARY 词重讲 |
teach | 跨多 session 系统学一个概念 |
setup-matt-pocock-skills | 一次性配置 tracker/标签/文档布局（本仓已完成） |
记忆口诀
三条推荐链路
小事 → tdd → code-review
中事 → grill-with-docs → implement
大事 → grill-with-docs → to-spec → to-tickets → implement-spec
收尾三连：评审 → code-review；提 PR → pr；复盘 → retro（/clear 前）
上下文纪律：grilling → to-tickets 一个窗口；逼近 smart zone 在阶段边界处理；换 harness/目录 → handoff
自动 skill 没触发时：换触发词 → 点名「用 xxx skill」→ 给路径「读 SKILL.md」→ 还是不行 → ask-matt
跑不通了怎么办
| 症状 | 怎么做 |
|---|---|
| grilling 一直问，问不完 | 说「够了，按你推荐的方案开始实现」，它会收 |
| 测试红了半天修不好 | 让它走 diagnosing-bugs，先建反馈环再改，别硬猜 |
| 一堆票不知道先做哪 | 看每张的 Blocked by 边，只做没有未完成前置的 |
| 上下文快满了 | 在阶段边界收：接着说、handoff、交给子代理、/clear |
| 它说的话听不懂 | /wait-what，让它用 GLOSSARY 的词重讲 |
| 自动 skill 没触发 | 换触发词 →「用 xxx skill」→ 让它读 SKILL.md → /ask-matt |
| retro 的建议落不了地 | 先补 lint / test / CI，它一半建议靠这些承载 |
几个行话：tracer-bullet 票 = 竖着切穿所有层、单张就能演示的票。seam = 你测行为的那条公开边界。深模块 = 接口小、内部厚的模块。smart zone = 模型开始丢细节的那条线，约 150k token。固定点 = 你给的一个基准，commit、分支、tag 都行。
