經過前面的經驗，我們寫的 Skill 終於能在對的時候被叫出來了。

流程寫得清楚、硬規則也定好了，用起來很順。

然後我又會開始想：既然這麼好用，那乾脆把更多東西寫進去吧。

但這樣又會出現什麼問題？

重點摘要

• Skill 把經驗全部往裡面塞，最後會整份被讀進去、重點被稀釋、沒人敢改
• 拆的標準：不太會變的「方法」留在 Skill，會一直累積的「素材」拆出去
• Skill 只留「這一步要做什麼 + 細節去哪看」，用到才讀，沒用到不佔 context
• 拆出去有兩種放法：references/ 是這支的附錄，獨立目錄才是知識庫
• 判斷標準：被兩支以上的 Skill 用到，就該獨立放
• QA 值得存的四類：排查路徑、踩過的雷、環境與架構、規格與測試案例

Skill 一直長大會發生什麼事

膽小狗英雄裡出現的胡蘿蔔：

以排查 Skill 為例，它一開始很單純，就是幾個步驟：

1. 看報告
2. 比對程式碼
3. 查 log
4. 翻舊 Bug 單

但實際用下去，你會忍不住一直補東西：

• 這次踩到一個雷
• 發現某個環境資料量大的時候本來就會慢
• API 的 log 跟 Web 的 log 看法不一樣
• 上次誤判過一次，把當時的判斷過程也

結果三個月後，這份 SKILL.md 從 80 行變成 800+ 行。

而這時候會出現三個問題：

1. 它整份都會被讀進去

Skill 一旦被觸發，SKILL.md 是整份載入的。

所以你排查一個單純的 timeout，AI 也得先把「iOS 模擬器的已知問題」「三年前那次 DB 遷移」等等通通讀一遍。

2. 重點被稀釋

這個比燒 token 更麻煩，因為資訊量太多太雜了，一個全部都是重點的文件其實就會變成沒重點了

AI 要在裡面自己判斷哪些跟這次有關，而它判斷錯的機率，會隨著雜訊增加而上升。

所以寫得越多，反而越不準。

3. 它變得沒人敢改

800+ 行的東西，你要新增一條規則之前，得先確認它跟前面有沒有衝突

• 會不會一改，原本可以正常執行流程突然就不執行了
• 會不會一改，原本準度又降低了

漸進式揭露：Skill 留方法規則，細節內文放別處

SKILL.md 通常盡量控制在 500 行內，細節搬到外面的檔案。

而這件事的關鍵，是拆的標準。

我自己的判斷很簡單：

Skill 裝的是「不太會變的方法」，拆出去的是「會一直長大的素材」。

同樣講排查：

拆完之後，Skill 本體可能會長這樣：

## 流程

3. **查 log** — 依平台選對應的排查方式
   - API 的 log → 見 [api-troubleshooting.md](api-troubleshooting.md)
   - Web 的 log → 見 [web-troubleshooting.md](web-troubleshooting.md)

Skill 只說「這一步要查 log，以及該去哪裡查」。

至於 API log 有哪些常見陷阱、哪個欄位要特別看，全部在外面那份檔案裡，AI 真的走到這一步才會去讀。

（現實中也不會只有一個檔案就放了全部踩雷經驗！通常還是會依照類型去區分 ex. 401 相關可看 401.md、timeout 可看 timeout.md 諸如此類）

拆出去之後，要放哪裡？

這裡有一個分界，我覺得比前面都重要。

拆出去的檔案有兩種放法：

• 第一種是「這支 Skill 的附錄」
• 第二種才是我要講的核心 知識庫

可以再進一步問問自己：

• 排查 Skill 要用？
  • 判斷這次是不是同一個問題
• 產生測試案例的 Skill 也要用？
  • 這個雷應該被補一條案例進去
• 審查 PR 的 Skill 還是要用？
  • 這次改動有沒有又踩到

當發生了同一份經驗，三支 Skill 都需要。

如果它放在排查 Skill 的 references/ 底下，另外兩支就吃不到，最後你只能複製三份，這樣最後就容易讓精準度就會開始漂移。

所以判斷很單純：

一份內容只要被兩支以上的 Skill 用到，就可以搬出來獨立放。

那個位置，就是知識庫。

附上 Claude 官方的推薦 Skill 設計供參考，實際還是可以自行調整的，重點是「設計原則」清楚即可

brand-guidelines/
├── SKILL.md
├── scripts/        # Optional: executable code
├── references/     # Optional: additional documentation
└── assets/         # Optional: templates, images, data files

知識庫其實沒有那麼複雜

它單純就是一批寫下來、AI 讀得到、而且不綁在任何一支 Skill 底下的檔案。

以 QA 的工作來說，我覺得值得存的有這幾類：

1. 排查路徑

• 這類錯誤先看哪裡、再看哪裡、什麼情況要往哪個方向查
• 例如：測試 timeout → 先看歷史穩定度 → 穩定才往產品端查 → 不穩定才往腳本查

2. 踩過的雷

• 哪一次誤判過、當時看起來像什麼、真因其實是什麼
• 例如：間歇性 timeout 曾誤判為 Flaky，真因是後端寫入順序沒鎖
• 這一類的價值最高，因為它記錄的是「表面症狀跟真因不一致」的案例

3. 環境與架構

• 哪個環境比較慢、哪個時段資料不齊、哪個服務重啟會影響什麼
• 團隊中有使用到服務架構關係圖，了解每個服務之間的耦合、上下游關係

4. 規格與測試案例

• 預期行為的權威來源
• 沒有這個，AI 連「什麼叫做對」都不知道

5. 產品業務邏輯

• 跟規格有點類似，但不同之處在於：特殊術語、E2E 畫面操作邏輯或者特殊動線
• 團隊特殊術語通常都是僅存在團隊之間的默契
• E2E 元件位置也是很常迭代更新，往往有時候設計稿、規格會無法 100% 同步對準，這時候就能保存當下頁面的資訊內容

實際用起來的感覺

問「這個測試失敗是什麼原因」

回覆會是這樣：

這個症狀在知識庫中 xxx.md 有相似紀錄：三個月前同樣是間歇性 timeout，當時初判 Flaky，實際真因是後端寫入順序未鎖定
建議先確認這支測試的歷史穩定度，再決定往哪個方向查

重點在於它把「應該先確認什麼」講出來了

這件事沒辦法一次到位，通常就是靠實務經驗一次次的堆疊出來的。

所以 Skill 跟知識庫是什麼關係

不是二選一，是分工：

只有 Skill 沒有知識庫，AI 會照著正確的流程，但每次都從零開始判斷。

只有知識庫沒有 Skill，AI 手上一堆資料，卻不知道該按什麼順序用。

兩個合起來，才會出現「流程不漏、判斷又準」的效果，也能達到高品質的產出

不過講到這裡，有件事必須講清楚。

把經驗存起來、把面向補滿，確實能讓 AI 的判斷準很多。

但實際上真正在用 AI 的人是我們，我們還是本身要具備足夠專業度，才能真正靈活運用 AI

這也是我以前常常在判定是否具備 Senior 其中之一標準