Matt Pocock Skills 完整說明書
mattpocock/skills
是 TypeScript 教育者 Matt Pocock（AI Hero / Total TypeScript 作者）公開的日常工程技能集，
給 Claude Code、Codex 等 coding agent 使用——「真正的工程開發，不是 vibe coding」。
本頁詳解正式推廣的 22 個技能：每個的用途、使用情境與使用範例。
非官方繁體中文說明書 · 依 2026-07-10 的倉庫內容整理 · 每個技能均連回原始 SKILL.md 與官方文件
這套技能解決什麼問題？
作者針對 coding agent 四個常見失敗模式，各給了一組修法：
設計哲學：技能要小巧、易改、可組合，適用任何模型。不像 GSD、BMAD、Spec-Kit 那樣接管整個流程——控制權留在你手上。
30 秒安裝
- 執行安裝器：
npx skills@latest add mattpocock/skills
- 挑選要裝的技能與目標 coding agent，務必勾選
/setup-matt-pocock-skills
- 在你的 agent 裡執行
/setup-matt-pocock-skills：它會問你 issue tracker（GitHub / Linear / 本地檔案）、triage 標籤、文件位置
- 完成，開始使用
兩種呼叫方式
所有技能只在一條軸上分家——誰能呼叫它：
- user-invoked 只有你輸入
/技能名 才會啟動。負責「編排」流程。
- model-invoked 你可以叫，agent 判斷情境符合時也會自己啟動。承載「可重用的紀律」。
規則：user-invoked 技能可以呼叫 model-invoked 技能，但永遠不會呼叫另一個 user-invoked 技能。
工作流程全局圖
/grill-with-docs拷問式訪談磨利想法，同步寫 CONTEXT.md 與 ADR
↓
紙上談不定的問題？→ /handoff 出去 → /prototype 用丟棄式程式碼找答案 → /handoff 帶答案回來
↓
/to-spec多 session 的工作：把討論串合成規格發佈到 tracker（小工作直接跳 /implement）
↓
/to-tickets拆成 tracer-bullet 垂直切片票，各自宣告 blocking 邊
↓
/implement（每張票開全新 context）
內部驅動 /tdd 一紅一綠 → 收尾跑 /code-review → commit
三條匝道匯入主流程：/triage（外來 issue/PR 分診）、/diagnosing-bugs（東西壞了）、/wayfinder（大到裝不下的迷霧工程）
底層詞彙層隨時被引用：/domain-modeling（領域語言）、/codebase-design（深模組語言）
Context 衛生：從 grilling 到 /to-tickets 要留在同一個不中斷的 context window 裡完成——不要中途 compact 或 clear，讓訪談、規格、票建立在同一套思考上。之後每張票的 /implement 都開全新 session。上限是「smart zone」：最先進模型約 120k tokens 內推理仍然銳利，快到了就 /handoff 換新視窗。
22 個技能速查表
開始之前
裝好技能後的前置設定，以及迷路時的地圖。
/setup-matt-pocock-skills
user-invoked
用途
一次性設定精靈。為當前 repo 建立其他工程技能所依賴的三項設定：issue tracker（GitHub / GitLab / 本地 markdown / 其他）、triage 標籤詞彙（五個角色標籤對應的實際字串）、領域文件佈局（CONTEXT.md 與 ADR 放哪）。它是對話式而非腳本式：先探索 repo、逐節提問、給你看草稿確認後，才寫入 docs/agents/*.md 與 CLAUDE.md／AGENTS.md 的 ## Agent skills 區塊。
使用情境
- 第一次在某個 repo 使用這套工程技能之前——每個 repo 跑一次
- 想換 issue tracker（例如 GitHub 換成 Linear、Jira 或本地檔案）
/to-spec、/to-tickets、/triage 抱怨找不到 tracker 設定時
使用範例
/setup-matt-pocock-skills
- 你輸入指令。
- 它先掃描 repo：
git remote 指向哪、CLAUDE.md／AGENTS.md 存不存在、docs/agents/ 有沒有先前的設定、是不是 monorepo。
- 它逐節提問（一節一答）：A. issue tracker 用哪個（有 GitHub remote 就推薦 GitHub）；B. 是否保留五個預設 triage 標籤（
triage 沒裝就整節跳過）；C. 領域文件單一或多 context（非 monorepo 直接不問）。
- 它把要寫入的檔案草稿全部給你過目、讓你修改。
- 產出：
docs/agents/issue-tracker.md、domain.md（必要時加 triage-labels.md），並在既有的 CLAUDE.md 或 AGENTS.md 更新 ## Agent skills 區塊。之後可直接編輯這些檔案，不必重跑。
/ask-matt
user-invoked
用途
整套技能的路由器。你不必記住每個技能——問它就好。它載有完整的流程地圖：一條主流程（idea → ship）、三條匝道、程式庫健康保養、底下的詞彙層、跨 session 工具，以及每個技能之間怎麼銜接，據此告訴你當下情況該走哪條路。
使用情境
- 不確定現在的狀況該用哪個技能
- 剛裝好整套技能，想快速了解全貌
- 想知道兩個技能怎麼接（例如
/to-tickets 拆完票然後呢？）
使用範例
/ask-matt 我有個很大的功能想做，但需求還很模糊，該從哪開始？
- 你描述目前的處境。
- 它比對路由圖：太大、太模糊、一個 session 裝不下 → 建議
/wayfinder 建調查地圖；如果其實一個 session 磨得完 → 建議 /grill-with-docs。
- 產出：一條明確的路線與理由，例如「先
/wayfinder 把迷霧清掉，路清了接 /to-spec 併回主流程」。
主流程：idea → ship
大多數工作走的路：有個想法 → 磨利它 → 寫成規格 → 拆成票 → 逐票實作 → 審查提交。記住 context 衛生：磨想法到拆票要待在同一個 context window，實作每張票則開全新 session。
/grill-with-docs
user-invoked
用途
主流程的第一步，作者最受歡迎的技能之一。跑一場 grilling 拷問式訪談磨利你的想法，但同時驅動 domain-modeling：過程中敲定的術語當場寫進 CONTEXT.md 詞彙表、難以回頭的決策提議記成 ADR。有狀態、留下書面紀錄——這是它與無狀態的 /grill-me 唯一的差別（兩者共用同一個 grilling 原語）。作者稱這可能是整個倉庫最強的一招。
使用情境
- 在有 codebase 的專案裡要開始做任何新功能或改動——作者建議每次要改東西都先跑
- 想邊磨需求邊累積專案的共享語言，讓之後每個 session 的溝通越來越省 token
使用範例
/grill-with-docs 我想幫購物車加上折扣碼功能
- 你丟出想法。
- 它一次一題地拷問：折扣可疊加嗎？過期怎麼算？誰能發碼？每題都附上它的建議答案；查得到的事實自己查，決策留給你。
- 它邊聊邊寫文件：「折扣碼」「兌換」等術語進
CONTEXT.md；「用百分比折扣不用定額」這種難回頭的取捨提議記成 ADR。
- 產出：一段達成共同理解的討論串＋更新過的領域文件。工作量大就接
/to-spec，小就直接 /implement。
/grilling
model-invoked
用途
底層的訪談原語——/grill-me 和 /grill-with-docs 都是在跑它。行為約定：對計畫的每個面向不留情地訪談、沿設計決策樹逐分支解決依賴、一次只問一題（一次問一堆會把人搞暈）、每題附推薦答案；能在 codebase 查到的「事實」自己查，「決策」全部交給你；未經你確認達成共同理解，絕不動手執行。
使用情境
- 其他技能的內部環節自動觸發（
/triage 把需求 grill 成形、/wayfinder 定目的地、/improve-codebase-architecture 走設計樹）
- 你用「grill 一下」「stress-test 這個計畫」之類的措辭時，agent 會自己認出來
使用範例
幫我 grill 一下這個部署計畫
- 你丟出計畫（或另一個技能把它拉進來）。
- 它先探索 codebase 把查得到的事實查掉，然後一題一題問決策點：藍綠還是滾動部署？回滾條件是什麼？每題附建議答案。
- 產出：決策樹每個分支都有答案的共同理解——而且在你點頭之前它不會開始做。
/to-spec
user-invoked
用途
把當前對話（通常是剛 grill 完的討論串）合成一份規格（spec／PRD）發佈到 issue tracker。不再訪談——純粹綜合已經談好的內容。固定模板：問題陳述、解法、大量 user stories、實作決策、測試決策、範圍外、備註。發佈前會先跟你確認要在哪些接縫（seam）測試——偏好既有接縫、越高越好、全 codebase 越少越好。
使用情境
/grill-with-docs 磨完需求後，工作量大到需要多個 session（多 session 就走 spec → tickets 這條路）- 想把一段有價值的討論固化成可追蹤的正式文件
使用範例
/to-spec
- 你在 grill 完的同一個對話裡輸入指令（context 衛生：中間不要 compact）。
- 它探索 repo 現況，用專案的領域詞彙、尊重相關 ADR。
- 它提出測試接縫的規劃（例：「整條在 cart API 這一個 seam 測」）並跟你確認。
- 產出：按模板寫好的 spec，發佈到設定好的 tracker，貼上
ready-for-agent 標籤。下一步 /to-tickets。
/to-tickets
user-invoked
用途
把計畫、spec 或當前對話拆成一組 tracer-bullet 垂直切片票：每張票切一條窄但完整的路徑打穿所有層（schema、API、UI、測試），單獨可 demo、大小塞得進一個全新 context window，並宣告自己的 blocking 邊（被哪些票擋住）。本地 tracker 是一票一檔（.scratch/<feature>/issues/）；真 tracker 用原生 blocking 連結。寬幅重構（改一處炸全場的機械式改動）是垂直切片的例外——走 expand–contract 三段式。
使用情境
- spec 寫好後，拆成一張張可以在單一 session 內完成的工作
- 一個大改動需要規劃先後依賴，想清楚哪些能平行做
使用範例
/to-tickets
- 你在 spec 完成的同一對話輸入指令（或帶一個 spec 路徑／issue 號當參數）。
- 它視需要探索 codebase，找「先重構讓改動變容易」（prefactor）的機會。
- 它以編號清單展示拆法：每張票的標題／被誰阻擋／交付什麼行為，然後問你顆粒度對不對、依賴邊對不對、要不要合併或再拆。
- 產出：你核准後發佈——本地一票一檔、或 tracker 上一票一 issue（附
ready-for-agent 標籤）。之後照「frontier」順序（阻擋者都完成的票）逐張開新 session 跑 /implement。
/implement
user-invoked
用途
照 spec 或票實作。行為約定：盡量在預先同意的接縫走 /tdd；定期跑 typecheck 與單檔測試、最後跑一次完整測試套件；完成後用 /code-review 審查自己的工作；提交到當前分支。它是主流程的「執行引擎」——票已把該想的想完，它專心把事做完。
使用情境
/to-tickets 拆完後逐票執行——每張票用全新 context window- 改動小到一個 session 裝得下：grill 完直接在同一對話
/implement，不必經過 spec/tickets
使用範例
/implement .scratch/discount-codes/issues/01-schema-and-api.md
- 你開一個全新 session，把票交給它。
- 它讀票，然後以 TDD 一紅一綠地實作：先寫失敗測試、再寫最小實作。
- 它過程中反覆 typecheck 與單檔測試，收尾跑完整套件。
- 產出：功能完成、
/code-review 兩軸審過、commit 到當前分支。清掉 context，拿下一張 frontier 票。
/tdd
model-invoked
用途
測試驅動開發的參考紀律，讓紅綠循環產出值得留下的測試。核心內容：好測試的定義（透過公開介面驗證行為、讀起來像規格書、重構不會壞）；seam 紀律——只在「預先同意」的接縫寫測試，動筆前先問「公開介面是什麼、要測哪些 seam？」；三大反模式（實作耦合、套套邏輯——期望值必須來自獨立事實源、水平切片——先寫完所有測試再寫實作是大忌）；循環規則（先紅後綠、一次一片、重構屬於審查階段不在循環內）。
使用情境
- 想 test-first 蓋一個具體行為，不需要完整 spec
- 提到 red-green-refactor 或想寫整合測試時，agent 會自己啟動
/implement 內部自動驅動它
使用範例
/tdd 幫 parseDuration 加上 "1h30m" 格式支援
- 它先讀
CONTEXT.md 對齊詞彙，然後問：「公開介面是什麼？要在哪些 seam 測試？」你們先同意 seam。
- 它寫一個失敗的測試（紅）——期望值來自規格或已知正確的字面值，不是照抄實作邏輯。
- 它寫剛好能通過的最小實作（綠），不預寫未來的功能。
- 產出：一片一片垂直堆出來的功能＋一組像規格書、重構不壞的測試。
/code-review
model-invoked
用途
對 HEAD 與一個固定點（commit、分支、tag、merge-base）之間的 diff 做兩軸審查：Standards——守不守這個 repo 文件化的編碼標準，外加一組固定的 Fowler 十二式程式碼異味基線（repo 標準永遠優先、異味永遠是判斷題）；Spec——是否忠實實作了原始 issue／PRD。兩軸跑平行子代理互不污染 context，結果並列回報、絕不合併排名——因為一個軸的高分可能掩蓋另一個軸的失敗。
使用情境
- 想審一個分支、PR 或進行中的改動（「review since main」）
/implement 完成時自動觸發，當作提交前的把關
使用範例
/code-review main
- 它先驗證固定點解析得出來、diff 非空（壞 ref 在這裡就失敗，不會浪費兩個子代理）。
- 它找 spec 來源：commit 訊息裡的
#123、你給的路徑、docs/／specs/ 下的檔案；找不到就問你，真沒有就跳過 Spec 軸。
- 它同一則訊息發出兩個子代理：Standards 拿標準文件＋異味基線，Spec 拿規格全文。
- 產出：
## Standards 與 ## Spec 並列報告＋一行總結（各軸發現數與最嚴重問題），兩軸各自獨立。
匝道（on-ramps）
三種「先產生工作、再匯入主流程」的起點：外面湧進來的 issue、壞掉的東西、大到看不見路的工程。
/triage
user-invoked
用途
把 issue（設定開啟時連外部 PR 也算——「PR 是附了程式碼的 issue」）推過一個分診狀態機：兩個類別角色（bug／enhancement）＋五個狀態角色（needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix）。分診時會查 codebase 是否已實作、查 .out-of-scope/ 是否拒絕過、實際重現驗證回報者的宣稱，需要時進 grilling，最後產出 agent-ready 簡報。所有 AI 產生的留言一律加免責聲明開頭。
使用情境
- 積了一堆別人回報的 bug 與功能請求要清（「給我看有什麼需要注意的」）
- 針對單一 issue：「看看 #42」「把 #42 標成 ready-for-agent」
- 注意：
/to-tickets 產的票天生就是 agent-ready，不要拿去 triage
使用範例
/triage 給我看有什麼需要注意的
- 它查 tracker 分三桶呈現（最舊優先）：沒標籤的、
needs-triage 的、needs-info 但回報者有新回覆的。
- 你挑一個，例如 #42。
- 它讀完整 issue、搜 codebase 檢查是否早已實作、翻
.out-of-scope/ 看是否似曾相識，然後給你類別＋狀態建議，等你指示。
- 它驗證宣稱：照回報步驟重現 bug（重現失敗是強烈的
needs-info 訊號）。需要磨的話跑 grilling＋domain-modeling。
- 產出：套上角色標籤＋對應動作——
ready-for-agent 附一份 agent 簡報留言、needs-info 附具體問題清單、wontfix（拒絕的 enhancement）寫進 .out-of-scope/ 知識庫再關閉。
/diagnosing-bugs
model-invoked
用途
硬 bug 與效能回歸的六階段診斷紀律。靈魂是 Phase 1：先建一個「對這隻 bug 會變紅」的緊回饋迴圈（失敗測試、curl 腳本、CLI、headless browser、重放 trace、bisect 挖礦……十種手段按序嘗試），沒有紅色迴圈就不准提假設——先讀程式碼腦補理論正是這個技能要防的失敗。之後：重現＋最小化 → 一次列 3–5 個可證偽假設（單一假設會錨定）→ 一次改一個變數地插樁 → 先寫回歸測試再修 → 清理＋事後檢討。
使用情境
- 難纏的 bug：第一眼看不出原因、間歇性 flake、兩個已知良好狀態之間長出來的回歸
- 效能變慢（走 perf 分支：log 通常沒用，先量測基線再 bisect）
- 你說「diagnose」「debug this」或回報東西壞掉／很慢時，agent 會自己啟動
使用範例
/diagnosing-bugs 結帳頁偶爾把運費算成 0，重現不穩定
- 它花不成比例的力氣建迴圈：把觸發流程跑 100 次、平行化、加壓、注入 sleep——目標不是乾淨重現，是把重現率拉到可以除錯的程度。
- 它迴圈變紅後開始最小化：一次砍一個元素重跑，直到剩下的每個都是 load-bearing。
- 它列 3–5 個排序過的可證偽假設（「若 X 是原因，改 Y 應消失」）先給你看——你常有能瞬間重排序的領域知識。
- 它針對預測插樁：debugger 優先，log 一律帶
[DEBUG-xxxx] 標籤方便一鍵清除。
- 產出：在正確的 seam 先寫失敗的回歸測試 → 修好 → 測試轉綠 → 原始迴圈轉綠 → 清光插樁、把驗證成立的假設寫進 commit 訊息。若發現「沒有好接縫能鎖住這隻 bug」，這本身就是發現——交棒
/improve-codebase-architecture。
/wayfinder
user-invoked
用途
規劃「一個 session 裝不下、還籠罩在迷霧裡」的巨型工作。它在 issue tracker 上建一張共享地圖（標 wayfinder:map 的 issue），子票是一張張調查票（四型：research／prototype／grilling／task），一次一個 session 解一張，產出決策而非交付物，直到通往「目的地」的路完全清晰。核心概念：fog of war（還說不精確的問題先寫進 Not yet specified，能精確描述了才升級成票）、frontier（沒被擋、沒被認領的開放票）、out of scope（超出目的地的工作明確排除）。地圖與票一律用名字稱呼，不用光禿禿的編號。
使用情境
- greenfield 專案或巨型功能——連「要決定什麼」都還看不清
- 對照：
/grill-with-docs 磨的是一個 session 抱得動的想法；抱不動的交給 wayfinder
使用範例
/wayfinder 我們要把整個計費系統從 Stripe 搬到自建
- 它（建圖 session）先 grilling 定出目的地：這張圖要走到哪——例如「一份可執行的遷移 spec」。目的地決定範圍，所以最先定。
- 它再 grilling 一輪，這次廣度優先掃出所有開放決策與現在就能動的第一步。（若掃不出迷霧——路已經清了——就不需要地圖，直接停。）
- 產出：地圖 issue（目的地＋備註＋迷霧草圖）＋現在能明確化的子票，第二遍接上 blocking 邊。建圖就是一個 session 的工作，到此為止。
- 你之後每個 session 用
/wayfinder <地圖> 回來：認領一張 frontier 票 → 解掉 → 答案留言＋關票＋在地圖 Decisions-so-far 加一行 → 把新明確化的迷霧升級成票。一個 session 只解一張。
- 終點：迷霧清光、路線清晰，併回主流程
/to-spec（工作變小了就直接 /implement）。
程式庫健康與詞彙層
不是功能開發，是保養——加上兩個在所有技能底下運行的詞彙參考：words, not process。
/improve-codebase-architecture
user-invoked
用途
掃描 codebase 找深化機會——把淺模組（介面幾乎跟實作一樣複雜）變深模組的重構——目標是可測試性與 AI 可導航性。產出一份視覺化 HTML 報告（寫到暫存目錄並自動打開）：每個候選一張卡，含涉及檔案、問題、解法、以 locality/leverage 說明的收益、前後對比圖、推薦強度徽章（Strong／Worth exploring／Speculative），結尾給出首選建議。你挑一個之後進 grilling 走設計樹。作者建議每隔幾天跑一次，拯救逐漸變成爛泥球的 codebase。
使用情境
- 有空檔想保養 codebase，讓它對 agent 更好操作
/diagnosing-bugs 事後檢討發現「沒有好接縫能鎖住 bug」時的指定交棒對象- 選定的深化機會＝一個新想法，可帶回主流程
/grill-with-docs
使用範例
/improve-codebase-architecture
- 它先讀
CONTEXT.md 與 ADR，然後派 Explore 子代理有機地走 codebase，記錄摩擦：懂一個概念要跳好幾個小模組、介面跟實作一樣複雜的淺模組、為了好測抽了純函式但 bug 全藏在呼叫端。可疑處套用「刪除測試」：刪掉它複雜度會集中還是只是搬家？
- 產出：HTML 報告寫到暫存目錄並自動打開，一卡一個候選＋前後對比圖＋推薦強度。與 ADR 衝突的候選會明確標警告。
- 你挑一個想深入的候選。
- 它進 grilling 走設計樹：約束、依賴、深化後模組的形狀、seam 後面放什麼、哪些測試存活——過程中同步更新
CONTEXT.md；你以有分量的理由否決候選時，它會提議記 ADR 讓未來的掃描不再重複建議。
/codebase-design
model-invoked
用途
設計深模組的共享詞彙表——大量行為藏在小介面後面、放在乾淨的接縫上、透過介面即可測試。精確定義八個詞（module、interface——呼叫者必須知道的一切，不只型別簽名、implementation、depth、seam、adapter、leverage——呼叫者從深度得到的、locality——維護者從深度得到的），並約定不准說 component／service／API／boundary。原則：刪除測試、「介面即測試面」、「一個 adapter 是假想接縫，兩個才是真的」。它是 /tdd 與 /improve-codebase-architecture 底下共用的語言層。
使用情境
- 想設計或改善某個模組的介面、決定 seam 要放哪
- 想讓程式碼更可測試、更好讓 AI 導航
- 架構討論的用詞開始飄（component、service 滿天飛）時，用它統一語言
使用範例
/codebase-design 幫我設計通知系統的介面，要支援 Email 和 SMS
- 它用詞彙表框住問題：seam 放在「發送通知」這一層；interface 收進呼叫者必須知道的一切（錯誤模式、順序約束，不只函式簽名）。
- 它檢查原則：Email 與 SMS 兩個 adapter 證明這個 seam 是真的；用刪除測試確認模組深度——刪掉它複雜度會在 N 個呼叫端重新長出來，代表它有存在價值。
- 它依「接受依賴而非創造依賴、回傳結果而非產生副作用、小表面積」設計出可測試的介面。要比較多種介面時，用 DESIGN-IT-TWICE 附錄的平行子代理模式設計好幾版再比。
- 產出：一個小介面＋深實作的模組設計，測試自然落在介面上。
/domain-modeling
model-invoked
用途
主動建立與磨利專案領域模型的紀律（只是「讀」CONTEXT.md 不算——這個技能是拿來「改」模型的）。行為：你的用詞和詞彙表衝突時當場指出；模糊或超載的詞（一個 "account" 幹三份工）逼你選一個精確的正名；用邊界情境壓力測試概念關係；和程式碼交叉比對找矛盾；決議一落地就當場更新 CONTEXT.md（純詞彙表，嚴禁放實作細節）；ADR 三條件全中才提議記（難回頭＋沒脈絡會驚訝＋真取捨）。
使用情境
- 想釘死專案術語，建立 ubiquitous language
- 要記錄一個架構決策（ADR）
/grill-with-docs、/triage、/wayfinder 的內部環節自動驅動它
使用範例
/domain-modeling 「account」這個詞在我們專案裡好像有三個意思
- 它列出三個用法：登入帳號、銀行帳戶、客戶主檔——並提議三個精確正名（User／BankAccount／Customer）。
- 它用具體情境逼精確：「一個 User 可以掛在兩個 Customer 底下嗎？」「Customer 刪除時 BankAccount 怎麼辦？」
- 它和程式碼比對：「你說可以部分取消，但程式碼只會取消整張 Order——哪個才對？」
- 產出：三個詞當場寫進
CONTEXT.md；若過程中做了難回頭的取捨（例如「客戶合併不保留歷史」），提議記一筆 ADR。
跨 session
context window 之間的橋樑——把一段對話的思考帶到下一個視窗。
/handoff
user-invoked
用途
把當前對話壓縮成一份交接文件，讓全新 session 的 agent 能接手。存到 OS 暫存目錄（不進工作區）；內含「建議技能」清單告訴下一個 agent 該啟用什麼；不重複 spec／ADR／commit 已記錄的內容——只給路徑或 URL；自動遮罩 API key 等敏感資訊。可帶參數描述下個 session 的用途，文件會照著剪裁。
handoff vs /compact：handoff 是「分岔」——你開一個全新 session、引用文件把脈絡帶過去；內建的 /compact 是「就地繼續」——留在同一對話、舊回合被摘要。階段之間的刻意休止用 compact（別在階段中間 compact，agent 會迷路）；需要全新視窗但要保留當前對話的，用 handoff。
使用情境
- context 快滿（接近 smart zone ~120k tokens 上限），不想在思考力下降的狀態下硬撐
- 主流程要分岔出去跑
/prototype，之後再把答案帶回來——雙向都靠它
使用範例
/handoff 下個 session 要用 prototype 驗證折扣疊加的狀態機
- 它把對話濃縮成 markdown：現況、已決事項、下一步、建議技能（
/prototype），存到暫存目錄並告訴你路徑。
- 你開新 session，把檔案路徑貼給新 agent。
- 新 agent 讀檔接手，帶著完整脈絡直接開工。
- 回程：prototype 得出答案後再
/handoff 一次，回到原討論串引用它。
獨立工具
完全在主流程之外、隨時單獨可用的技能。
/grill-me
user-invoked
用途
與 /grill-with-docs 相同的不留情訪談，但用在沒有 codebase 的情況。無狀態：不存任何本地檔、不建 CONTEXT.md。作者最受歡迎的技能之一——任何不住在 repo 裡的計畫都用它磨。
使用情境
- 磨任何非程式的計畫：行銷企劃、文章大綱、活動籌備、產品構想
- 想在動手前把一個決策的每個分支都想清楚
使用範例
/grill-me 我想辦一場 50 人的技術工作坊
- 它一次一題拷問：目標受眾是誰？預算上限？場地需求？成功怎麼衡量？每題附建議答案。
- 你逐題回答，它沿著決策樹往下走，一個分支一個分支解掉依賴。
- 產出：每個面向都敲定的共同理解——且未經你確認它不會動手執行。
/prototype
model-invoked
用途
丟棄式原型——用來回答一個設計問題的程式碼，問題決定形狀，兩個分支：「這個邏輯／狀態模型感覺對嗎？」→ 小型互動終端 app，把狀態機推過紙上難以推理的案例；「這個東西該長怎樣？」→ 同一路由上多個截然不同的 UI 變體，URL 參數＋浮動底欄切換。共同規則：天生丟棄並明確標示、一行指令可跑、預設不持久化、跳過打磨（不寫測試不做抽象）、每次操作後顯示完整狀態、答案才是要留的——記進 commit／ADR／NOTES.md，程式碼用完即刪或吸收。
使用情境
- 狀態模型講不清楚，要實際跑跑看才知道感覺對不對
- 頁面該長怎樣要看到才能決定
- 主流程的 detour：grilling 遇到需要「可執行的答案」的問題時，配
/handoff 進出
使用範例
/prototype 折扣碼疊加規則的狀態機感覺對嗎？
- 它判斷這是邏輯分支 → 蓋一個極小的互動終端 app，放在未來會用到它的模組旁邊、命名清楚標示是原型。
- 你用一行指令跑起來，把狀態機推過各種案例；每步它都印出完整狀態。
- 你得出答案：「疊加上限應該掛在 cart 層，不是 code 層。」
- 產出:答案記錄到 ADR 或 NOTES.md，原型刪除（或把驗證過的決策折進正式碼）。
/research
model-invoked
用途
把閱讀苦工外包給背景代理：對高信任第一手來源（官方文件、原始碼、規格、第一方 API——不是別人的二手整理）調查一個問題，每個主張都追回擁有它的來源，寫成一份有引用的 Markdown 存進 repo（跟隨 repo 既有的筆記慣例位置）。它在背景跑，你手上的工作不中斷。
使用情境
- 需要查證 API 行為或文件事實，但不想中斷目前的工作
- 產出的檔案帶進
/grill-with-docs 當思考素材——research 餵思考，不取代思考
使用範例
/research Stripe webhook 的重試行為到底是怎樣？
- 它派出背景代理去讀 Stripe 官方文件與 API 參考，每個主張追到源頭。
- 你繼續做手上的事。
- 產出：一份每個主張都附引用的 Markdown（例如
docs/research/stripe-webhook-retries.md，位置跟著 repo 慣例），回頭讀完就能帶進下一場 grilling。
/teach
user-invoked
用途
多 session 的教學工作區。把當前目錄當有狀態的學習空間：MISSION.md（你為什麼想學——所有教學圍繞它）、RESOURCES.md（高信任資源，絕不信任模型自己的記憶）、lessons/（一課一個精美自包含的互動 HTML，短小、快速可完成、落在你的最近發展區）、reference/（課程濃縮成的速查頁——課很少回看，參考頁會）、learning-records/（學習紀錄，用來推算下一課教什麼）。教學哲學：知識靠高信任來源、技能靠 desirable difficulty（檢索練習、間隔、交錯）、智慧靠真實社群。
使用情境
- 想系統性地學一個主題，分多次學（程式、物理、瑜伽都行）
- 希望學習有累積：每次回來它記得你學到哪、該教什麼
使用範例
/teach 我想學 Rust 的所有權系統
- 它第一件事是問你為什麼想學（要寫 CLI 工具？轉職？），寫進
MISSION.md——不懂動機，課程就會太抽象。
- 它找高信任資源（官方 Book、Rustonomicon）填入
RESOURCES.md。
- 產出：一課短小、互動、帶引用的 HTML（含小測驗，選項字數一致不洩題），並濃縮出一頁所有權規則速查表放進
reference/。
- 下次回來：它讀
learning-records/ 推算你的最近發展區，接著教 borrow checker。
/writing-great-skills
user-invoked
用途
寫好技能的參考書（本身全是 reference、沒有步驟）。核心論點：技能存在的目的是從隨機系統裡擰出確定性，可預測性（每次跑同樣的「過程」）是根本美德。內容涵蓋：model-invoked vs user-invoked 的成本取捨（context load vs cognitive load）；description 寫法（前置 leading word、一個分支一個觸發、砍掉同義改寫）；資訊層級三層梯（in-skill step → in-skill reference → external reference）與漸進揭露；何時拆分；修剪紀律（單一事實源、逐句獵殺 no-op）；leading words（用模型預訓練裡現成的緊湊概念——如 tracer bullets、fog of war——錨定行為）；六大失敗模式（premature completion、duplication、sediment、sprawl、no-op、negation——禁止句反而讓大象更鮮明，要正面陳述）。
使用情境
- 要寫一個新技能，或編輯既有技能
- 診斷技能的毛病：為什麼觸發不穩定、agent 為什麼不照做
使用範例
/writing-great-skills 幫我看看我這個技能為什麼常常不觸發
- 它用參考書診斷 description：leading word 沒有前置、三個觸發句其實是同一個分支的同義改寫（duplication）。
- 它修 description：關鍵詞放最前面、一個分支留一個觸發、砍掉 body 裡已有的身分描述。
- 產出：順手再掃 body——揪出 no-op 句（模型本來就會做的事）與 sediment 層（沒人敢刪的陳年段落），整個技能更短、觸發更準。
/resolving-merge-conflicts
model-invoked
用途
解決進行中 git merge／rebase 衝突的五步紀律：看清現狀（git 歷史＋衝突檔案）→ 為每個衝突找第一手來源（commit 訊息、PR、原始 issue——深入理解兩邊各自為什麼這樣改）→ 逐 hunk 解決（盡量保留雙方意圖；不相容時選符合這次合併目標的一方並記下取捨；絕不發明新行為、永遠解決、絕不 --abort）→ 找出並跑專案的自動檢查（typecheck → tests → format），修掉合併弄壞的 → 完成 merge／rebase（stage、commit，rebase 就 continue 到底）。
使用情境
- rebase 到一半滿螢幕
<<<<<<< 衝突標記
- 合併一條放很久的長壽分支
使用範例
（rebase 卡住時）幫我解掉這些衝突
- 它先
git status／git log 看衝突全貌。
- 它對每個衝突讀兩邊的 commit 訊息、PR、原始 ticket，弄懂雙方原意。
- 它逐 hunk 解決：能保留雙方意圖就保留；不能就選合併目標那一方並記下取捨。
- 產出：typecheck／tests／format 全過、合併完成——rebase 的話一路 continue 到所有 commit 都 rebase 完。