🛠 Skills For

🎯 什麼情境該想到我

當你的 skill 從 3 個長到 15 個，開始重複、開始互相呼叫、開始沒人記得哪個還能用的時候。

⚙️ 怎麼用（步驟 / 公式）

1. ⭐ 用「誰能叫它」分成兩層——這一條決定其他所有事

層	誰能叫	職責
user-invoked	只有人打指令	編排：把一連串步驟串起來
model-invoked	人或模型都能	持有可複用的紀律：一件事的正確做法

規則：user-invoked 可以呼叫 model-invoked，但絕不呼叫另一個 user-invoked。
這條把依賴圖壓成兩層，不會長成任意呼叫的網。

2. 重複的段落要抽成 model-invoked 原語

發現三個 skill 裡有同一段「怎麼訪談使用者」，那就抽出來變成一個 model-invoked skill，讓上層共用。
實例：grilling 這個面談原語被 grill-me、grill-with-docs、triage、wayfinder、improve-codebase-architecture 五個編排型 skill 共用。
判準：同一段紀律出現第二次，就該抽。

3. 給 skill 一個晉升生命週期

用資料夾分級，並明確規定哪一級才會出現在對外清單：

bucket	意義	出現在 README／清單？
engineering/、productivity/	promoted，正式供應	✅ 必須
in-progress/	公開但未出貨，徵求回饋	❌ 禁止
misc/	留著但很少用，不推廣	❌ 禁止
deprecated/	已停用	❌ 禁止

沒有這層分級，實驗品跟正式品會混在一起，清單很快失去可信度。

4. ⭐ 有路由就要維護——「會說謊的路由」

如果你有一個「該用哪個 skill」的入口，把同步更新寫成硬規則：

新增、改名、移除、或改變任何 user-reachable skill 時，必須重讀路由的 SKILL.md 並更新它。
一個它從沒提過的新 skill，或一個它還在路由過去的舊 skill，就是一個會說謊的路由。

5. 每個 skill 的文件用固定四段

What it does／When to reach for it／Common questions／It’s working if。
最後那段最少見也最有用——它讓使用者能自己判斷 skill 是否真的生效，而不是只能猜。

6. 用 symlink 連進 harness 目錄

把 skill 以 symlink 連進 ~/.claude/skills／~/.agents/skills，這樣 git pull 就等於更新已安裝的版本，不必重裝。新增或改名後重跑連結腳本。

🧪 我實際套用的紀錄

• 2026-08-28：（待填）

⚠️ 注意 / 什麼時候不適用

• 少於 5 個 skill 不需要這套。分層與 bucket 是規模到了才有的問題，太早做只是額外負擔。
• 分層要落到設定、不能只寫在文件上：user-invoked 要真的關掉模型觸發（例如 disable-model-invocation: true 加上對應 agent 設定裡的 allow_implicit_invocation: false），否則規則會被繞過。
• 抽共用原語會增加一層間接。只在同一段紀律真的出現第二次時才抽；為了「將來可能會用」而抽，是在製造維護成本。
• 路由是最容易腐爛的一環，因為它不會報錯。要靠流程規則盯住，不能靠自覺。
• 改了共用的 model-invoked 原語，上層每一個編排 skill 都要重驗 → 工具-測試skill的觸發邊界。

🔗 相關工具

• 工具-把重複的prompt包成skill —— 那張是「單一 skill 怎麼誕生」，這張是「一堆 skill 怎麼不腐爛」
• 工具-測試skill的觸發邊界 —— 分層之後，哪些能被模型自動叫起來就是可測的行為，要驗
• 工具-防止agent造假通過驗收 —— 「It’s working if」跟那張的心法一致：把「成功」定義成可判定的東西

🎯 什麼情境該想到我

當你「交代完需求，agent 埋頭做完，你一看發現它完全誤解」的時候——或者更常見的：你自己其實也還沒想清楚。

「沒有人確切知道自己要什麼。」——《Pragmatic Programmer》

⚙️ 怎麼用（步驟 / 公式）

核心是把提問方向反轉：不是你交代 agent，是 agent 先拷問你。

1. 動工前明講要進拷問模式：「在開始寫之前，針對這個設計持續問我問題，直到每個分支都有答案為止。不要開始寫程式。」
2. 要求它窮盡設計樹的分支，而不是問三題就收工。判準是「還有沒有沒決定的分支」，不是「問夠多題了」。
3. 一輪問完「現在能問的」，每題附建議答案。Matt Pocock 目前的 grilling skill 先把設計畫成一棵樹，每一輪只問前提都已經定案的那些題（frontier）：每題編號、各附一個建議答案，而且措辭設計成回「yes」就等於採用建議；答案依賴本輪其他未定題的，留到下一輪。你答完，樹往外長，再算下一輪。查得到的事實由 agent 自己查（派 sub-agent 去看檔案、環境），只有決策丟給你。等到沒有未定的分支、而且你確認雙方理解一致，才算結束。（1.2.0 以前是一次只問一題；改成整輪問後，同樣 13 題約 3 輪問完。查證 2026-10-15）
4. 不知道就說不知道——這正是最有價值的訊號，代表那裡是真的風險點，該記下來當開放問題，而不是讓 agent 幫你假設掉。
5. 同時把行話固定下來。拷問過程中出現的專案術語，順手寫進 GLOSSARY.md（Matt Pocock 的 skill 在 1.3.0 前叫 CONTEXT.md），之後每個 session 都受用 → 工具-通用語言。
6. 拷問完才產出規格，然後才動工。

🧪 我實際套用的紀錄

• 2026-08-28：（待填）

⚠️ 注意 / 什麼時候不適用

• 小改動不要用。改個文案、修個明顯的 bug，拷問的成本遠大於誤解的成本。
• 它會很煩，那是特性不是缺陷。覺得被問到不耐煩時，通常正是你原本會出事的地方（我的判斷）。
• 要明確叫它「先不要寫」，否則多數 agent 問兩題就自己開工了（經驗推論）。
• 這不能取代你自己想。它逼你面對沒想過的分支，但答案還是你要給；對建議答案回「yes」沒問題——那是你看過之後做的決定；但如果每題都回「你決定就好」、連建議都沒看，就等於跳過了決策，拷問只是換一種方式讓 agent 自己猜（我的判斷）。
• 跟需求前置條件不同：工具-建構的先決條件 講的是「專案該先確立哪些事」（人的流程），這張講的是「怎麼跟 agent 把它挖出來」（互動手法）。兩張搭配用。

🔗 相關工具

• 工具-通用語言 —— 拷問的最佳副產品：把專案行話固定下來，之後 agent 不用每次重猜，回應也更精簡
• 工具-建構的先決條件 —— 該被問出來的東西有哪些，看那張的清單
• 工具-曳光彈開發 —— 如果拷問後發現需求真的無法確定，那就別再問了，改用曳光彈先打通端到端

🎯 什麼情境該想到我

當你「發現 agent 反覆犯同一類錯、你一直在 CLAUDE.md／AGENTS.md 補規則，但下次它還是錯」的時候。

⚙️ 怎麼用（步驟 / 公式）

核心想法：別只修這次的程式碼，要改的是讓錯誤更難發生的環境。來自 Matt Pocock 的 retro skill，在一個 coding session 結束後跑。

1. 讀第一手紀錄，不靠記憶

回顧的對象是 session 本身：本機的 session log、指令與輸出。要在 /clear 之前、在被回顧的那個 session 裡做；clear 之後就只能指向 log 檔。

2. 依七類找改善點（每類都有「什麼時候才看」）

類別	問什麼	何時看
導航	agent 花多久才找到對的檔案？檔案之間有沒有隱藏依賴？加一行導航指標會不會更快？	找資訊花了很久
自動檢查	有沒有 lint、型別、測試、檔案規則能抓到這個錯？先讀 repo 既有的 check 指令與 CI：已經存在卻沒接上、或悄悄壞掉的檢查，本身就是發現；完全沒有防護（沒有 pre-commit、CI 也不跑 lint／typecheck／test）也是發現	agent 犯了機器抓得到的錯
程式規範	reviewer 該不該多執行一條規則？該刪或改清楚哪一條？	reviewer 漏抓
全域 AGENTS.md	哪些指示該搬去規範或自動檢查？	檔案太大
工具經濟	有沒有昂貴的工具呼叫可以精簡？哪個 CLI 或 MCP 特別耗 token？	出現昂貴呼叫
No-op	哪些指示根本沒改變 agent 的行為？	指示檔又大又亂
資訊取得	能不能讓 agent 看到更多？例如把 dev server log 接出來、開第三方服務的唯讀權限	關鍵資訊 agent 拿不到

3. ★ 規範要先分類：機械性的寫成檢查，判斷性的才寫成文字

• 機械性違規（固定的語法模式、禁用的 API、import 形狀、檔案位置規則）→ 一律做成確定性檢查：repo 自己 linter 的自訂規則、新的 pre-commit hook，或新的 CI job，挑最便宜的一種。預設是寫檢查，不是寫規則。
• 判斷性的事（跨檔一致性、「跟周邊風格一致」這類任何防護都取代不了的）→ 才寫進 CODING_STANDARDS.md。

理由很直接：寫在文字裡的規則要靠 agent 每次記得，而且一直佔 context；檢查則每次都會跑、而且確定。

4. 把規範交給壓力最小的角色

• 實作 agent 的 context 壓力最大（要探索、寫碼、除錯）；review agent 只收一份 diff，壓力最小。所以程式規範由 reviewer 執行，不由實作者執行。
• 對應的檔案分工：
  • CLAUDE.md／AGENTS.md 會推進每個 agent 的 context，只放導航指標。
  • CODING_STANDARDS.md 只在 review 時讀，超過約 1000 行就拆檔，用指標連過去。
  • 文件當參考檔，由其他檔指過去。

5. 刪掉 no-op

逐句問：「這句跟模型本來就會做的比，有沒有改變行為？」沒有就整句刪。太弱的詞換成有力的詞，例如「be thorough」換成「relentless」。這條出自同一個 repo 的 writing-for-agents，retro 第一步就是載入它。

6. 依嚴重度排序後提給人決定

產出是一份建議清單，由人挑要做哪些；retro 本身不改檔。

🧪 我實際套用的紀錄

• 2026-10-13：對照本庫，/obsidian-kb:lint-wiki 的機械掃描已經腳本化，語意判斷交給 lint-depth，剛好就是「機械性寫成檢查、判斷性才給 LLM」的分法。

⚠️ 注意 / 什麼時候不適用

• 需要讀得到 session log；harness 不保留紀錄時只能回顧當下這一輪。
• 順利的 session 不必做：原文件建議在「值得學點什麼」的 build 之後跑，順利的 build 可以跳過；每次 session 都跑多半只會產出沒人需要的規則（retro 文件）。會反覆在同一個 repo 工作的 agent 回報最大（我的判斷）。
• 建議會越來越多，要依嚴重度挑，不是每次全做；每類的「何時看」條件就是用來避免每次七類都跑一遍。
• 「把規範交給 reviewer」的前提是你真的有 review 階段，例如雙軸 code review 或 CI；沒有的話，規則只能留給實作者（推論）。

🔗 相關工具

• Skills For Real Engineers —— 這個做法所在的 skill 集合，以及整條流程裡 retro 的位置
• 工具-skill集合的分層與維護 —— 規則、skill、指示檔要放哪一層
• 工具-防止agent造假通過驗收 —— 確定性的檢查也是防止 agent 自稱完成的手段
• 工具-知識庫定期健檢 —— 同樣的分法套在知識庫上：機械項先腳本化