mattpocock/skills 的自我介紹只有一句話：Skills for Real Engineers. Straight from my .agents directory.
這句話的重點在後半段——這不是為了教學而寫的範例集，是作者每天真的在用的那份設定，原封不動放上來。這篇先講清楚它是什麼、為什麼存在、以及它跟 GSD、BMAD、Spec-Kit 那類「AI 開發框架」的差別在哪。下一篇再寫完整的安裝與使用步驟。
一、這個 repo 是什麼
先看幾個客觀數字（撰文時實際查詢 GitHub API 的結果）：
| 項目 | 數值 |
|---|---|
| 建立時間 | 2026-02-03 |
| Star | 210,223 |
| Fork | 18,164 |
| 授權 | MIT |
| 正式收錄的 skill 數 | 25 個 |
| 目前版本 | 1.2.3 |
作者 Matt Pocock 是 TypeScript 社群相當知名的教學者（Total TypeScript、AI Hero）。這個 repo 半年就衝到二十萬星，本身就說明了一件事：大家不缺會寫程式的 agent，缺的是讓 agent 好好做工程的紀律。
所謂 skill，就是一個資料夾裡放一份 SKILL.md——一段寫給 agent 看的指示文件，加上 YAML front matter 描述它叫什麼、什麼時候該用。Claude Code、Codex 這類 agent harness 會讀這些檔案，讓你用 /skill-name 呼叫，或是在情境符合時自動採用。
二、它的立場：不接管你的流程
README 開頭那段話是整個 repo 的定位宣言，值得原文引一次：
Developing real applications is hard. Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve.
These skills are designed to be small, easy to adapt, and composable.
翻成白話：**那些框架的問題不是做得不好，是它們把流程整個吃下去了。**當流程本身出錯的時候，你很難修——因為你根本不知道它在哪一步做了什麼決定。
這個 repo 選了相反的路：每個 skill 都小、都是純 Markdown、都可以單獨用、也可以互相組合。你不喜歡哪一段就改哪一段。作者甚至直接在 README 裡說 Hack around with them. Make them your own.
這個取捨對誰有意義？如果你是那種「agent 產出的東西我要看得懂、也要有能力介入」的人，這個方向會合你的胃口。如果你想要的是「輸入需求、輸出完整專案」的一條龍，那它不是你要的東西。
三、它想修的四個失敗模式
README 用四個標題把「agent 開發為什麼會爛掉」講得很直接，我覺得這是整份文件最有價值的部分——因為每一個都太熟悉了。
#1 The Agent Didn’t Do What I Want
“No-one knows exactly what they want” —— The Pragmatic Programmer
最常見的失敗是對齊失敗。你以為 agent 懂了，看到成品才發現它從頭到尾理解錯。
他的解法叫 grilling（拷問）：在動手之前，讓 agent 反過來瘋狂質問你，把設計樹上每一個沒想清楚的分支逼出來。對應的 skill 是 /grill-me（通用）和 /grill-with-docs（附帶建立專案文件）。作者說這兩個是他最受歡迎的 skill，建議每次要改東西之前都跑一次。
#2 The Agent Is Way Too Verbose
這一段的觀察很敏銳。他引 Eric Evans 的 DDD：專案初期，工程師和領域專家講的是兩種語言。而 agent 的處境更慘——它被丟進一個專案，得自己猜裡面的黑話，所以只好用二十個字講一件本來一個詞就能講完的事。
解法是建立一份共用語言（CONTEXT.md）。README 裡的例子很傳神：
- 之前：「當課程某個章節裡的課程被『實體化』（也就是在檔案系統裡取得位置）時會出問題」
- 之後：「materialization cascade 有問題」
他說這可能是整個 repo 裡最酷的技巧，而且好處不只是省字：變數和檔案命名會一致、agent 在程式碼庫裡導航更容易、連思考用掉的 token 都變少。
#3 The Code Doesn’t Work
就算對齊了，agent 還是可能產出爛東西。這時候該檢查的是回饋迴路——沒有回饋，agent 等於閉著眼睛飛。
對應的是 /tdd（強制 red-green-refactor，並且明確定義什麼是好測試、什麼是壞測試）和 /diagnosing-bugs（把除錯最佳實踐包成一個分階段、有閘門的迴路）。
#4 We Built A Ball Of Mud
“Invest in the design of the system every day.” —— Kent Beck
這是最容易被忽略的一個：agent 加速了寫程式，也就同時加速了軟體的熵增。程式碼庫變複雜的速度是前所未有的。
對應的是 /codebase-design（深模組的共通紀律與詞彙）和 /improve-codebase-architecture（掃描整個 codebase，把可以「加深」的候選點做成 HTML 報告給你挑）。作者建議每隔幾天跑一次。
這裡他講了一句很誠實的話，我特別欣賞：這是調查，不是搶救（It is a survey, not a rescue）——在真正老舊的專案上它找得到問題，但它不會幫你把爛泥解開。
四、關鍵設計：誰可以呼叫這個 skill
這是整個 repo 架構上最重要的一條軸線，也是我認為最值得學起來的設計。所有 skill 依「誰能呼叫」分成兩類：
| User-invoked（使用者呼叫） | Model-invoked（模型可呼叫） | |
|---|---|---|
| 誰能觸發 | 只有你打出它的名字 | 你或 agent 自己判斷 |
| 設定方式 | front matter 加 disable-model-invocation: true |
不加（預設） |
description 寫給誰看 |
人——一句話的摘要 | 模型——要寫滿觸發語句 |
| 職責 | 編排流程 | 承載可複用的紀律 |
而且有一條硬規則：user-invoked 可以呼叫 model-invoked，但永遠不能呼叫另一個 user-invoked。
為什麼要這樣分？因為兩種 skill 的 description 根本是寫給不同讀者看的。model-invoked 的描述要塞滿「Use when the user wants…, mentions…, asks for…」，這樣自動觸發才會準；user-invoked 的描述則要拿掉那些觸發語，因為它只會出現在人類瀏覽的斜線指令清單裡，寫成觸發語只會讓人看不懂。
實際比較兩份 front matter 就很清楚：
1 | # grill-me —— user-invoked，描述寫給人看 |
1 | # tdd —— model-invoked，描述塞滿觸發條件 |
判斷一個 skill 該不該保持 model-invoked，repo 裡給的測試很簡潔：模型有沒有可能自己主動用得上它？（注意「可複用」不是判準——可複用只是抽出成 skill 的理由。）
五、25 個 skill 的全貌
flowchart TB
subgraph A["對齊：先問清楚要做什麼"]
G1["/grill-me"]
G2["/grill-with-docs"]
end
subgraph B["規劃：變成可執行的東西"]
S1["/to-spec"]
S2["/to-tickets"]
S3["/wayfinder"]
end
subgraph C["執行：真的寫下去"]
I1["/implement"]
I2["/tdd"]
I3["/diagnosing-bugs"]
end
subgraph D["守門：不要越寫越爛"]
R1["/code-review"]
R2["/codebase-design"]
R3["/improve-codebase-architecture"]
end
A --> B --> C --> D
D -.->|發現新問題| A
完整清單分成 engineering 和 productivity 兩大桶：
Engineering / user-invoked：ask-matt（不知道該用哪個就問它，它是個路由器）、grill-with-docs、triage、improve-codebase-architecture、setup-matt-pocock-skills、to-spec、to-tickets、implement、wayfinder。
Engineering / model-invoked：prototype、diagnosing-bugs、research、tdd、domain-modeling、codebase-design、code-review、resolving-merge-conflicts、wizard。
Productivity / user-invoked：grill-me、handoff（把當前對話壓縮成交接文件）、teach、to-questionnaire、wait-what（訊息看不懂時按這個，agent 會用你的 CONTEXT.md 詞彙重講一次）。
Productivity / model-invoked：grilling（前面那些拷問 skill 共用的底層原語）、writing-for-agents（怎麼寫給 agent 看的文件）。
幾個我覺得設計得特別聰明的：
ask-matt——一個「我該用哪個 skill」的路由器。25 個 skill 確實記不住，與其寫一份沒人看的對照表，不如做成 skill 本身。wait-what——訊息看不懂的當下就按。它不會叫你去查文件，而是用專案自己的詞彙把同一件事重講一次。code-review——沿兩條軸線審查：Standards（有沒有遵守這個 repo 的規範，加上 Fowler 的 code smell 基線）和 Spec（有沒有忠實實作原本的需求）。關鍵是這兩條跑在各自獨立的 sub-agent 裡並行，這樣兩邊的 context 不會互相汙染，最後才彙整。
六、兩種安裝方式，其實是兩種哲學
這點 README 講得很明白，我覺得比安裝指令本身重要：
The Claude Code plugin installs the whole set as a managed, read-only bundle that updates when I ship — you subscribe rather than fork. skills.sh copies editable skill files into your project, so you can hack on them and make them your own. Pick one — installing both leaves you with every skill twice.
| Claude Code plugin | skills.sh | |
|---|---|---|
| 心態 | 訂閱——作者更新你就跟著更新 | 分叉——檔案是你的，你自己改 |
| 檔案位置 | 統一的外部快取，唯讀 | 直接寫進你的 repo |
| 更新 | 自動 | 手動 npx skills update |
| 適合誰 | 想開箱即用、跟著上游走 | 想改造成自己的一套 |
最後那句警告要記住：兩種都裝的話，每個 skill 都會出現兩次。
順帶一提，repo 裡的 ADR 0002 記錄了「為什麼有 Claude Code plugin 卻沒有 Codex plugin」，讀起來像一份小型技術偵探報告：Claude Code 的 plugin.json 的 skills 欄位接受路徑陣列，所以可以精準挑出要發布的那批；Codex 只接受單一路徑字串，而這個 repo 的 skill 分散在 engineering/ 和 productivity/ 兩個資料夾裡，還有 deprecated/、in-progress/、personal/ 不該發布。他試過用 symlink 做一個扁平目錄，結果 Codex 安裝時會把整棵樹複製進快取、symlink 直接被丟掉，skill 到達時是空的。
這種「我試過 A 和 B，各自為什麼失敗」的紀錄，比結論本身有價值得多。
七、誠實的注意事項
寫這篇的時候我把整個 repo clone 下來翻過，有幾件事值得先知道：
skill 是提示詞，不是程式。 它們是寫給模型看的 Markdown，所以效果會隨模型能力浮動，也不保證每次行為一致。它沒辦法像 lint 規則那樣強制執行任何事。
25 個 skill 的學習成本是真的。 別想一次全上。從 /grill-me 開始，把「動手前先被拷問一輪」變成習慣，就已經拿到這個 repo 大半的價值了。ask-matt 的存在本身就承認了這個問題。
engineering 那一整套預設你有 issue tracker。 to-spec、to-tickets、triage、wayfinder 全都在讀寫 issue。沒有這個習慣的話，可以在 setup 時選 local markdown，但整條流程的重量還是在的——它就是為「有規模的專案」設計的。
全英文。 SKILL.md 都是英文，agent 讀沒問題，但如果你想改成中文語氣，那就是 fork 路線（skills.sh）才方便做的事。
官方 marketplace 的版本會落後。 ADR 裡自己揭露了這件事：官方清單指向這個 repo 的 git URL 而且 sha 是釘住的，所以新版是在那個釘子往前移的時候才會到你手上，不是他一 tag 就到。作者寫那份 ADR 的當下，釘子就落後 main 兩個 commit，導致清單顯示 22 個 skill 而不是 plugin.json 裡的 24 個。
下一篇寫完整的實作步驟：怎麼裝、/setup-matt-pocock-skills 到底幫你寫了哪些檔案、以及一條從拷問到 code review 的完整流程長什麼樣子。
留言