xufang5219/agent-skills

問問 Matt

你不需要記住每個技能，所以來問吧。

在陳述一個技能的功能或建議跳過某個步驟之前，請先閱讀該技能的 SKILL.md：這裡的摘要僅供參考。

流程是貫穿各技能的路徑。大多數路徑沿著一條主流程進行，並有兩個合流點與之匯合。其他一切都是獨立技能，或者是運作在底層的詞彙層。

主流程：構思 → 交付

這是大多數工作遵循的路徑。你有一個想法，並希望它被建立起來。

1. /grill-with-docs 透過訪談來打磨想法。當你在工作目錄中工作時，從這裡開始：它是有狀態的，會將學到的內容保留在 GLOSSARY.md 和 ADR 中。（沒有工作目錄？請改用 /grill-me，詳見獨立技能部分。兩者都執行相同的 /grilling 基本操作；grill-with-docs 會留下文件記錄，因此只要有儲存庫可以留下記錄，它就是較好的選擇。）
2. 分支：你能在對話中解決所有問題嗎？ 如果一個問題需要可運行的答案（狀態、業務邏輯、必須看到的 UI），則繞道透過原型進行，並透過 /handoff 進行雙向橋接（原型位於自己的目錄中，這正是 /handoff 的用途；請參閱階段邊界）：
   • 使用 /handoff 輸出，然後針對該檔案開啟一個新的會話視窗，
   • 使用 /prototype 用一次性代碼回答問題，
   • 使用 /handoff 將學到的內容帶回，並從原始想法討論串中引用它。
3. 分支：這是一個需要多個會話的建構嗎？
   • 是 → 使用 /to-spec（將討論串轉換為規格說明），然後使用 /to-tickets 將其分割為「導引子彈」工單，每個工單宣告其阻塞邊界。然後以下列兩種方式之一處理工單：
     • 每個工單使用 /implement，並在每個工單之間使用 /clear 清除上下文。在本機追蹤器上，這是在 .scratch/<feature>/issues/ 下一個工單一個檔案，手動先處理被阻塞的工單；在真正的追蹤器上，邊界會變成原生的阻塞連結，因此任何其阻塞項已完成的工單都可以被挑選。每個工單都是自包含的，所以最後一個工單的上下文是可以丟棄的。
     • 對整個規格說明一次使用 /implement-spec。它將工單讀取為任務圖，跨已就緒的前沿並行執行實作子代理，並將所有內容合併到一個整合分支上。當你更傾向於編排建構過程而不是親自驅動每個工單時，可以考慮使用此方法。
   • 否 → 在此處，相同的上下文視窗內，直接使用 /implement。

無論哪種方式，代碼都是透過驅動 /tdd（一次一個紅-綠循環）來建構的，並以 /code-review 結束，這是一個針對 diff 的雙軸審查（標準 + 規格）。/implement 每個工單都會執行這兩者；/implement-spec 的實作者各自驅動 /tdd，並且它會在整合分支上執行一次 /code-review。當你只想在沒有完整規格的情況下，以測試優先的方式建構一個具體行為時，可以單獨使用 /tdd；而當你想針對一個固定點審查任何分支或 PR 時，可以單獨使用 /code-review。

當工作以 Pull Request 的形式提交時，/pr 會塑造其主體：顯示變更的最小視覺效果、證明其運作正常的前後對比證據，以及單向或雙向決策的呼叫。它是由模型調用的，所以代理在撰寫 PR 時會自動使用它。

4. /retro 閉合循環。在一次建構之後，特別是當事情偏離軌道時，它會回顧會話，並建議對代理的環境（而非代碼）進行更改：導航指標、自動化檢查、/code-review 強制執行的編碼標準、導引檔案、工具鏈。機械性錯誤變成確定性檢查；判斷取捨變成編碼標準。下一次建構將從更好的環境開始。

上下文衛生

將步驟 1–3 保持在一個不間斷的上下文視窗中（在 /to-tickets 之前不要壓縮或清除），這樣打磨、規格和工單都在相同的思考基礎上建構。然後每個 /implement 從頭開始，根據工單進行工作。在清除上下文之前，在要回顧的會話中執行 /retro；清除之後，則將該會話的日誌指向它。

這方面的限制是智慧區：模型在此視窗內仍能清晰推理（在最先進的模型上約為 150k tokens）。如果在 /to-tickets 之前會話接近此限制，不要在效能下降時硬撐；在最接近的階段邊界處使用 /compact 並繼續進行（請參閱階段邊界）。

合流點

一個會產生工作，然後匯入主流程的起始情境。

• 錯誤和請求不斷累積 → 使用 /triage。它透過分類角色來處理問題，並產出代理可用的問題，這些問題之後由 /implement 接手。

  分類僅適用於不是你建立的問題：錯誤報告、收到的功能請求，任何原始未經處理的內容。由 /to-tickets 產生的工單已經可供代理使用，所以不要對它們進行分類。

• 某個東西壞了 → 使用 /diagnosing-bugs。專為棘手的問題設計：一眼看不出來的錯誤、間歇性的不穩定、在兩個已知良好狀態之間悄悄出現的迴歸問題。它拒絕在擁有緊密回饋迴路（一個已經能針對這個錯誤顯示紅色的指令）之前進行理論推斷，然後用回歸測試來修復。修復完成後，在同一個會話中執行 /retro 來詢問是什麼可以預防這個錯誤；如果真正的發現是沒有好的隔離點來鎖定它，那麼這就是 /improve-codebase-architecture 的工作。

• 一個龐大、模糊的工作：一個全新專案或一個巨大的功能建構，太大而無法在一個會話中完成 → 使用 /wayfinder，這是這裡認知負荷最高的流程。當從這裡到目的地的路徑尚不明確時，它會在問題追蹤器上繪製一個由決策工單組成的共享地圖，並逐個解決它們，產出決策而非交付物，直到迷霧被推開，路徑清晰可見。當 /grill-with-docs 打磨的是可以在一個會話中掌握的想法時，wayfinder 則是針對你無法掌握的想法，它更慢、更密集，所以請只在這種情況下使用它，永遠不要用於範圍明確的功能。

  當地圖清晰後，它進行交接，而不是建構：匯入主流程中的 /to-spec，它將地圖中連結的決策收斂成一個可建構的計劃，然後照常進行 /to-tickets 和 /implement。將地圖直接送進 /implement 會跳過這個收斂步驟，並丟失連結的細節，所以只有當工作結果證明真的很小時，才直接跳到 /implement。

代碼庫健康

不是功能開發，只是維護。

• /improve-codebase-architecture 在你空閒時執行，以保持代碼庫適合代理運作。它會浮現深化的機會；挑選一個機會會產生一個想法，你可以將其帶入 /grill-with-docs 的主流程。它是發現候選項目的調查；/codebase-design（見下文）則是設計所選項目的工作檯。

底層詞彙

兩個由模型調用的參考，運作在其他技能之下，各自是其詞彙的唯一真實來源。當字詞（而非流程）是問題時，直接使用它們；或者讓上述技能拉取它們。

• /domain-modeling：打磨專案的領域語言：質疑模糊的術語、解析過載的詞彙（例如「account」身兼三職）、將難以回退的決策記錄為 ADR。這是 /grill-with-docs 所驅動的主動紀律，以保持 GLOSSARY.md 成為一份乾淨的詞彙表。
• /codebase-design 是深層模組詞彙（模組、介面、深度、隔離點、轉接器、槓桿作用、局部性），用於設計模組的形狀：在一個乾淨的隔離點上，透過一個小的介面呈現大量的行為。/tdd 和 /improve-codebase-architecture 都會使用它。

階段邊界

階段是一個會話內的工作區塊：打磨、實作、品質保證。在兩個階段的邊界處，你有五個選項，而在整個地圖中，挑選它們之間是最模糊的決策：

• 繼續：保持不變。沒有成本，不會遺失任何東西。
• /clear：清空視窗，當這裡的內容對下一步不重要時使用。
• /handoff 寫入一個可攜帶的 Markdown 檔案。用途狹窄：僅用於新的測試架構、新的目錄、同事，或者在階段中途分岔一個側邊任務。它帶來的好處是可攜帶性。
• 子代理：將一個範圍緊密的任務傳送到它自己的視窗，並取回一份報告。
• /compact 壓縮當前上下文，並用它來初始化一個新的會話。預設選項，位於決策樹的底部而非頂端。

請閱讀 PHASE-BOUNDARIES.md 以了解排序的決策樹：五個問題、每個分支背後的理由，以及為什麼主要來源成本使得繼續成為第一個要排除的選項。在邊界處做出決策；在階段中途，繼續進行，或者將剩餘部分拆分給子代理。

獨立技能

完全脫離主流程。

• /grill-me：與 /grill-with-docs 相同的無情訪談，但是無狀態的：它不會在本機儲存任何內容，也不會建立 GLOSSARY.md。當你不在工作目錄中工作時（例如打磨計劃、設計、某篇文章，或任何沒有儲存庫在下的東西），請使用它。如果你在工作目錄中，請改用 /grill-with-docs：它執行相同的訪談並留下文件記錄，因此它嚴格來說是更好的選擇。
• /grilling 是訪談基本操作本身：輪次、前沿、事實是代理的工作，決策是你的工作。/grill-me 和 /grill-with-docs 是兩種命名的入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都在內部運行它。僅當你想要沒有包裝器的訪談時，才直接使用它。
• /prototype 是一個小型、一次性使用的程式，用於回答一個設計問題：這個狀態模型感覺對嗎？或者這個 UI 應該長什麼樣子？一次性使用是對程式碼撰寫方式的約束，而不是銷毀它的承諾：答案會融入真正的代碼中，而原型本身會作為主要來源保存在一個基於主分支的 prototype/<name> 分支上，並從實做工單中指向它。這是主流程步驟 2 中的繞道，但任何時候當設計問題難以在紙上解決時，都可以使用它。
• /research：將閱讀的基礎工作委派給一個後台代理：它針對主要來源調查一個問題，然後在儲存庫中留下一個附有引用的 Markdown 檔案。讓它在閱讀時，你可以繼續工作。它產生的檔案是要帶入 /grill-with-docs 主流程的內容，因為研究為思考提供養分，而不是取代思考。
• /to-questionnaire 在你遇到的阻礙不在你的頭腦或代碼庫中，而是在別人的腦子裡時使用，它會為他們撰寫一份問卷來填寫。它是 /grill-me 的逆向操作：它不是訪談你關於主題，而是訪談你關於發送對象（問卷要寄給誰，你需要什麼回覆），並針對資訊缺口提出問題。回覆的內容是 /grill-with-docs 或 /to-spec 的材料。
• /wizard 用於只有人類才能執行的步驟：佈建基礎設施、設定憑證或 CI 密碼、點擊不熟悉的第三方儀表板、執行一次性遷移或切換。它會產生一個互動式 bash 腳本，開啟每個 URL、捕獲每個值，並將其寫入 .env 和 GitHub Secrets，這樣該程序就不再需要你每次向代理重新解釋。它由模型調用，所以代理在遇到只有你能通過的障礙時就會自動使用它。如果代理可以自己完成，它應該自己做；這是在人類真正參與迴路時才用的。
• /wait-what 是針對沒有被正確理解的訊息的修正機制。在對話中途，在任何其他技能內部使用它，代理會使用 GLOSSARY.md 的詞彙，用淺顯的英語重新解釋它剛剛說過的內容，並補充你所缺失的上下文。它是在事後發揮作用；/grill-with-docs 是事前的預防措施，因為早期達成共識的通用語言能從根本上阻止行話的產生。
• /teach：在多次會話中學習一個概念，使用當前目錄作為有狀態的工作空間。
• /writing-for-agents 是為代理編寫文件（技能、AGENTS.md、指向的文件）的參考指南。

前置條件

/setup-matt-pocock-skills：在你的第一個工程流程之前運行，以配置其他技能所依賴的問題追蹤器、分類標籤和文檔佈局。自定義的問題追蹤器也可以使用。