Matt Pocock skills 1.3 釋出：implement-spec、pr 與 retro 工作流詳解

Matt Pocock 於 2026 年 10 月釋出 skills v1.3，新增 /implement-spec、pr 與 /retro。 這座在 GitHub 累積逾 29.2 萬顆星、超過 2.4 萬次 Fork 的開源技能庫，在 v1.3 正式版更新中把重心轉向程式碼周邊的驗證與協作。此外，領域詞彙檔 CONTEXT.md 也全面更名為 GLOSSARY.md。當 AI 代理寫程式的成本大幅下降，工程團隊的真正瓶頸已轉移至多工單平行調度、Pull Request（PR）審查負荷，以及儲存庫環境的持續改善。

四階段基底與 1.3 版後半場：區分使用者觸發與模型自動載入技能

在 1.3 版之前，開發者主要依賴四個基礎技能完成開發前半場。第一階段是 /grill-with-docs（或 /grill-me）。它會讓代理先探索現有儲存庫，再針對需求細節展開多維度提問，直到雙方認知完全對齊。第二階段是 /to-spec。當需要開啟新對話視窗時，它會把對談結論整理為包含使用者故事與驗收條件的標準規格文件。第三階段是 /to-tickets。它負責依縱向切片（Vertical Slices）拆出帶有阻塞關係（Blocked by）的多張獨立工單。第四階段則是 /implement，針對單一工單執行測試驅動開發（TDD）。

這四個步驟解決了前半場的需求收斂，卻留下後半場的三個人工痛點。首先，多張相依工單必須由人類逐一手動觸發。其次，AI 產生的 PR 描述常過於冗長難讀。最後，代理在對話中踩過的環境陷阱無法自動轉為防護欄。1.3 版新增的三個技能正是為了補齊後半場流程。

在深入個別技能前，必須先釐清 mattpocock/skills PR #1120 嚴格執行的雙層呼叫架構。全庫 27 個技能分為兩類：

• 使用者觸發技能：定義檔會標註 disable-model-invocation: true。這類技能包含 /grill-with-docs、/to-spec、/to-tickets、/implement、/implement-spec 與 /retro。它們屬於頂層協調器，只能由人類主動輸入命令啟動。任何技能都不得在內部自動呼叫另一個使用者觸發技能。
• 模型自動載入技能：包含 grilling、tdd、code-review、domain-modeling 與 1.3 版晉升的 pr。它們代表可重用的工程紀律。1.3 版將跨技能引用語法統一改為 Call the Skill tool with "grilling"。這項調整消除了對 Claude Code 斜線語法的耦合，也解決了 /grill-with-docs 偶爾漏載入底層提問規則的問題。

升級 1.3 必讀的破壞性變更：CONTEXT.md 全面更名為 GLOSSARY.md

1.3 版包含兩項直接影響既有儲存庫配置的變動。第一，領域詞彙檔由 CONTEXT.md 更名為 GLOSSARY.md。多語境索引檔 CONTEXT-MAP.md 也同步更名為 GLOSSARY-MAP.md。早期名稱源自領域驅動設計（DDD）的限界上下文。然而 CONTEXT.md 字面過於空泛，導致模型經常在需要核對術語時漏讀該檔案。

更名後，包括 domain-modeling、grill-with-docs、tdd 與 pr 等 11 個技能只會讀取 GLOSSARY.md。團隊升級時必須在同一個 Commit 中執行更名並同步拉取。否則未同步成員的代理會在舊檔旁新建一份空白的 GLOSSARY.md。

第二，官方正式移除了 /resolving-merge-conflicts 技能。現行主力模型與代理執行環境已具備原生解衝突能力，無須再維護獨立技能。

# 1. 更新技能套件並手動清除已移除的舊技能資料夾
npx skills update
rm -rf .agents/skills/resolving-merge-conflicts

# 2. 將既有領域詞彙文件更名為 1.3 版指定檔名
git mv CONTEXT.md GLOSSARY.md
git mv CONTEXT-MAP.md GLOSSARY-MAP.md
git commit -m "chore(docs): rename CONTEXT.md to GLOSSARY.md for mattpocock/skills v1.3"

/implement-spec：以任務相依圖與 Git Worktree 平行調度子代理

當 /to-tickets 從規格拆出七、八張帶有 Blocked by 相依關係的工單時，過去工程師必須自己扮演調度器。你得先跑完未阻塞的工單 1 與工單 2，再手動啟動工單 3。Matt Pocock 在 /implement-spec 官方指南中將多工單執行歸納為三種模式。第一種是人類逐張執行的「手動迴圈」。第二種是由外部程式穩定觸發 /implement 的「確定性迴圈（如 Sandcastle）」。第三種則是由主代理動態調度背景子代理的「代理迴圈（即 /implement-spec）」。

當團隊尚未建置外部確定性流水線，卻希望透過多代理跨視窗交接與分工策略一次消化整份規格時，/implement-spec 提供了開箱即用的平行執行能力。

根據官方技能定義檔，1.3 版的目標是將整份規格收斂至單一整合分支（Integration Branch）。它不會直接對主幹開啟多張零碎 PR。其八階段流程如下：

1. 驗證追蹤器設定：確認已提供工單路徑，否則提示執行 /setup-matt-pocock-skills。
2. 解析任務相依圖與可執行前沿（Frontier）：讀取所有工單的阻塞關係，找出當前無未完成前置條件的工單集合。主代理只負責調度，不直接修改業務程式碼。
3. 派發唯讀探索子代理：若多張工單涉及相同模組，先由探索子代理將關鍵路徑與慣例寫入儲存庫外的共用筆記。這能避免後續子代理重複搜尋相同檔案。
4. 建立整合分支：從預設分支切出整合分支並推送至遠端。
5. 在隔離 Git Worktree 啟動實作子代理：針對前沿上的每張工單，以 isolation: "worktree" 背景平行啟動實作子代理。每個子代理會確認分支切自整合分支，接著載入 tdd 技能完成測試優先開發。在回報完成前，子代理會先將整合分支最新末端（Tip）合併回自身分支並跑過測試。
6. 合併子代理（Merger Subagent）快轉推進：每當實作子代理完成，合併子代理便以快轉（Fast-forward）方式將其併入整合分支。若追蹤器規定以 PR 關閉工單，才會在第一張工單併入後開啟 Draft PR。隨著前置工單完成，下游阻塞工單隨即解鎖進入新前沿。
7. 整合分支整體審查與修正：所有工單併入後，主代理載入 code-review 審查整條整合分支，並派單一修正子代理修復問題。
8. 清理環境與結案：移除所有臨時 worktrees 與過渡分支，將整合分支標記為可審查狀態。

官方也提醒兩個實務限制。第一，最終產出是一條涵蓋整份規格的大分支。第二，平行 worktree 只是將衝突延後到合併期。例如兩張工單可能用不同名稱新增同一欄位，這類問題仍須仰賴代理驗證與自動化合併防線與最終的 code-review 攔截。

pr 技能：以「由下而上」閱讀順序與單／雙向門風險加速審查

當代理寫完程式碼，人工審查就成為交付瓶頸。AI 預設產生的 PR 描述常把修改檔案逐一列點，卻掩蓋了潛在的系統風險。1.3 版晉升的 pr 技能屬於模型自動載入技能，當代理準備建立 PR 時會自動套用。若開發工具內建其他格式，亦可在 AGENTS.md 指定提交 PR 時強制載入 pr。

pr 技能規定描述只包含三個區塊，且審查者應採取「由下而上（Bottom-up）」順序閱讀：

1. 最底層先看合併風險（## Merge Danger）：代理必須先回答變更屬於雙向門還是單向門。接著再標示爆炸半徑（Blast Radius）。雙向門代表隨時可透過 git revert 無痛回滾。單向門則涉及刪除資料表欄位或發送外部通知等不可逆操作。若一個 PR 為雙向門且爆炸半徑僅限單一元件，審查者即可快速放行。若為單向門或波及全端，則必須逐行嚴審。
2. 中間層檢視客觀證據（## Evidence）：強制要求代理提供修改前（Before）與修改後（After）的實測對比。這能防止代理只讀完程式碼就宣稱功能正常。視覺介面變更必須提供 S 級證據（修改前後真實截圖）。後端邏輯變更則須提供 A 級證據（例如修改前回傳 HTTP 500，對比修改後回傳 HTTP 200 與通過測試輸出）。
3. 最頂層閱讀最小視覺化摘要（## Summary）：此設計借鏡了 Humanlayer 創辦人 Dex Horthy 的 show-me 技能。它規定摘要必須是能一眼看懂架構差異的最小視覺表達，例如目錄結構差異、虛擬碼、呼叫樹或 Mermaid 圖表。

Matt Pocock 釋出 1.3.0 的官方 PR（mattpocock/skills#1120）即由 pr 技能直接產生：

以下為套用 pr 模板的全端金流狀態遷移範例：

## Summary

將結帳狀態機由布林旗標改為顯式狀態列舉，並補齊冪等金流回呼檢查。

  src/modules/checkout/
  ├── webhook-handler.ts       # + 新增冪等金鑰鎖定與狀態轉換檢查
  ├── schema.sql               # ! 將 is_paid 布林欄位替換為 payment_status 列舉
  └── __tests__/
      └── webhook.spec.ts      # + 涵蓋重複回呼與亂序事件的整合測試

## Evidence

- 修改前（Before）：重複傳送相同 event_id 回呼時觸發唯一鍵衝突並回傳 HTTP 500；pnpm test 失敗（1 failed）。
- 修改後（After）：重複回呼穩定回傳 HTTP 200 OK；pnpm test 共 14 項斷言全數通過，pnpm typecheck 零錯誤。

## Merge Danger

Door: 單向門（One-way door）——包含移除舊版 is_paid 欄位的資料庫遷移，部署後無法直接回滾舊版程式。
Blast Radius: 結帳模組與帳務查詢——所有讀取訂單付款狀態的查詢皆已同步改讀 payment_status。

/retro：把機械式規則轉為確定性檢查，讓 AGENTS.md 越寫越短

代理在開發過程中常在背景默默繞路，例如猜錯匯入路徑或跑錯測試命令。雖然最終功能得以交付，卻消耗了大量時間與 Token。1.3 版新增的 /retro（回顧檢討）會在對話結束或 /diagnosing-bugs 修完臭蟲後啟動。它會審視整段對話紀錄與工具呼叫日誌，針對「代理的工作環境」提出改善清單。

/retro 會依嚴重度檢查七個面向：

1. 程式碼導覽性（Navigation）：依循 John Ousterhout 提出的「深模組」原則。它會找出讓代理迷路的隱藏相依與缺失導覽指標。
2. 自動化檢查防線（Automated Checks）：確認 Linter、型別檢查與測試是否接上 pre-commit hook 與 CI。若儲存庫毫無自動化防護欄，會直接列為首要缺失。
3. 編碼規範分流（Coding Standards）：將規範違規嚴格拆分為兩類。凡是能用程式判定的機械式違規（Mechanical Violations），一律轉為自訂 Linter 規則或 pre-commit 檢查。因為檢查腳本會直接報錯攔截，而寫在 Markdown 裡的文字警告不會。唯有需要上下文權衡的判斷型原則才寫入 CODING_STANDARDS.md。該檔案會交由低上下文壓力的 code-review 子代理審查。
4. 全域 AGENTS.md 瘦身：只保留導覽指標與核心命令。
5. 工具與 Token 經濟（Tool Economy）：封裝消耗大量 Token 的冗長 CLI 輸出。
6. 刪除無效指令（No-ops）：移除指導檔中「請撰寫乾淨易讀的程式碼」等不會改變模型行為的贅字。
7. 執行期資訊存取（Information Access）：例如將開發伺服器日誌透過 tee 寫入檔案，讓代理能直接讀取錯誤。

Matt Pocock 特別警告絕對不要將 /retro 設為全自動執行。無人把關的自動回顧會針對單次偶發現象產生偽陽性診斷，不斷往儲存庫堆疊無用規則。正確做法是由人類從 /retro 產出的清單中挑選真正痛點予以落實，讓 AGENTS.md 隨時間越寫越短。

常見實務誤區：依上下文預算決定是否跳過 /to-spec 與 /implement-spec

使用這套工作流最常見的錯誤，就是不論需求大小都機械式走完四階段拆票流程。若只是修改單一 API 或新增表單欄位，強行拆票與建立多個 Git worktree 只會浪費 Token 與等待時間。

工程師應根據「剩餘上下文視窗預算」採取三路分流：

• 路徑 A（單一視窗直通車）：執行 /grill-with-docs 對齊後，若功能單純且上下文空間充裕（僅用約 30%～40%），請直接跳過 /to-spec。你可以在原對話直接執行 /implement → pr → /retro。
• 路徑 B（跨視窗規格交接）：若對齊階段翻閱大量檔案導致上下文逼近飽和，但功能本身無須平行拆票，則執行 /to-spec 產出規格檔。接著清空對話（/clear）開啟新視窗，再執行 /implement。
• 路徑 C（多工單平行任務圖）：唯有面對跨層級大型功能或廣域重構時，才完整執行 /to-spec 與 /to-tickets。最後再呼叫 /implement-spec 動員平行 worktree 子代理推進整合分支。

常見問題

升級到 mattpocock/skills 1.3 版後，原本的 CONTEXT.md 不改名會怎樣？

1.3 版中包括 grill-with-docs、tdd 與 pr 等 11 個技能已完全停止讀取 CONTEXT.md。若未執行 git mv CONTEXT.md GLOSSARY.md，代理下次執行時會在舊檔旁新建一份空白的 GLOSSARY.md。這會導致既有領域術語定義失效。

/implement-spec 與外部 Shell 迴圈跑 /implement 有何差異？

外部 Shell 迴圈（確定性迴圈）是由腳本按固定順序逐一呼叫代理執行單張工單，穩定且省 Token，但需自行搭建執行器。/implement-spec 則由主代理動態解析 Blocked by 任務圖。它會為未阻塞的前沿工單平行開啟隔離 Git worktree，並收斂至單一整合分支。

為什麼 pr 技能建議審查者從最底部的 Merge Danger 開始往上讀？

先看底部的 Merge Danger 能在數秒內確認變更屬於可隨時回滾的「雙向門」還是不可逆的「單向門」，以及出錯時的「爆炸半徑」。若為低風險雙向門且影響範圍極小，往上看一眼 Evidence 的測試紀錄即可合併，無須耗時逐字閱讀長篇背景。

/retro 抓出的問題應該寫進 AGENTS.md 還是 CODING_STANDARDS.md？

兩者皆非首選。凡是能用程式判定的機械式違規，一律優先改寫為自訂 Linter 規則或 pre-commit hook。只有無法靜態判定的設計權衡才寫入 CODING_STANDARDS.md 供審查子代理參考。至於全域 AGENTS.md 則僅保留精簡導覽指標。

權威資料來源

• AI Hero：Skills v1.3 正式版更新公告（/implement-spec, /pr, /retro, and GLOSSARY.md）
• GitHub：mattpocock/skills 官方開源儲存庫與 v1.3.1 Release
• GitHub：mattpocock/skills PR #1120（v1.3 三大技能晉升與實測 PR 範本）
• GitHub：Humanlayer show-me 視覺化摘要技能定義
• Anthropic：Claude Code Skills 與 Subagents 官方技術文件

Author Insight

若團隊日常開發有八成以上屬於單一模組內的功能迭代，升級 1.3 版後最該立即啟用的是 /grill-with-docs 直通 /implement。接著再搭配 pr 與每週一次的 /retro，把機械式錯誤沉澱為 Linter 規則。唯有當單一規格拆出 4 張以上具備明確平行前沿的工單時，才值得動用 /implement-spec 承擔多 worktree 合併的協調成本。

I'm a Full Stack Developer with expertise in building modern web applications that fast, secure, and scalable. Crafting seamless user experiences with a passion for headless CMS, Vercel and Cloudflare

Loading...