打造 AI Agent Skills 框架 — 收斂審查
14 個 Skills 長大之後怎麼做系統性治理？47 項發現、三階段收斂、術語統一的實踐紀錄
三週密集開發之後，我停了下來。
不是沒事做。是意識到一個問題：14 個 Skills 個別品質都還行，但放在一起看，全局一致性正在劣化。
同一個概念在不同 Skill 裡有不同的描述。同一份 API 參考被複製了 7 次。同一個術語經歷了三代命名，但舊名稱還殘留在各處。
一個個 Skill 單獨看沒毛病。但生態系整體在累積技術債。
10 天的沉默
這裡有一個有趣的節奏。在收斂審查之前，開發進入了 10 天的沉默期——沒有任何 commit。
不是刻意安排的。就是工作上有其他事情，暫時放下了框架的開發。
但回頭看，這 10 天的沉默反而是關鍵的。密集開發時，你看到的是每個 Skill 的局部問題。停下來一段時間之後再回來，看到的是全局的系統性問題。
視角從「這個 Skill 還缺什麼」轉變成了「這 14 個 Skill 作為一個整體，有什麼問題」。
47 項發現
帶著全局視角，我做了一次全量審查——14 個 Skills，逐一過一遍。
47 項發現。按嚴重度分成四級：
| 嚴重度 | 數量 | 典型問題 |
|---|---|---|
| Critical | 5 | 無效引用、邊界模糊、命名衝突 |
| High | 12 | 知識重複、缺失段落 |
| Medium | 18 | 精簡機會、冗餘內容 |
| Low | 12 | 表述細節、格式不一致 |
最關鍵的發現是：4 個 Skills 的「領域知識」佔比超過了 45%。
這意味著 Gotchas Only 原則——Skill 只放坑點和決策，領域知識放到 Docs——沒有被徹底執行。事件規格、API 參數、元件細節，這些應該在 Docs 裡的東西，仍然散落在 Skills 裡。
同時，7 個知識點被複製到了多個 Skill 中。每份複本的措辭略有不同，AI 遇到矛盾時就會困惑。
三階段收斂
47 項不可能一次全改。一次改太多，回歸測試會爆炸——你無法分辨新出現的問題是哪次修改造成的。
分三個階段：
Phase 1：Critical + Quick Wins。 先處理無效引用（指向不存在的檔案路徑）和空殼檔案。這些改動風險低、影響明確。淨減 65 行。
Phase 2：Token 效率。 把 7 個重複的知識點統一到 Docs，Skills 裡只留引用。最大的一次改動是把分散在 4 個 Skills 裡的 API 參數表，合併到前端知識庫的一個章節裡。淨減 160 行。
Phase 3：品質強化。 補齊遺漏的邊界案例、強化驗證 checkpoint、完善反向引用。這個階段反而增加了 50 行——但增加的都是品質增量。
為什麼先做 Critical + Quick Wins？
因為前兩類改動的因果關係最清楚。無效引用刪掉就是刪掉，不會有副作用。重複知識統一到 Docs，邏輯也很明確。先處理這些，把「確定能改好」的東西清掉，剩下的再慢慢處理。
回歸測試的角色
每個 Phase 完成後，跑一輪回歸測試。
Phase 2 之後的回歸結果：12/13 通過，1 個缺口。
那個缺口是什麼？一個版型的事件清單裡，有兩個事件在瘦身過程中被意外移除了。回歸測試生成的程式碼缺少了這兩個事件的處理邏輯。
補回來，重新跑，13/13 通過。
如果沒有回歸測試，這個缺口可能要等到真實的使用場景中才會被發現。瘦身 Skills 和瘦身程式碼一樣——你以為是刪冗餘，實際上可能刪到了有用的東西。回歸測試是安全網。
術語統一：三代命名的混亂
收斂審查中最耗時的一項工作是術語統一。
框架裡有一套規格書模板系統，用來把人類撰寫的需求規格轉換成 AI 可消費的結構化格式。這套系統在開發過程中經歷了三代命名：
第一代：用層級編號——L0、L0.5、L1、L2、L3。很精確，但沒有語意——看到「L2」你不知道是什麼。
第二代：簡化成兩個階段——G0（初始格式）和 G2（結構化格式）+ HWS（人類可撰寫規格書）。好一些，但 G0/G2 和 HWS 的關係不清楚。
第三代：從流程角度重新命名——舊格式 → HWS（Human-Writable Spec）→ AIS（AI-Structured Spec）。每個名稱對應規格書在流程中的一個階段，語意清晰。
問題是三代命名在文件中混合存在。同一份規格書模板，在 Skill A 裡叫「L2」，在 Skill B 裡叫「G2」，在 Docs 裡叫「AIS」。
統一涉及 16 個檔案、70 多處修正、8 個 commits。
這個工作機械、枯燥，但極其必要。術語不統一，AI 的理解就不統一。你叫它「用 L2 格式」，它不確定你說的是 G2 還是 AIS——因為它在不同的文件裡看到過不同的名稱指向同一個東西。
收斂審查的時機
什麼時候該做收斂審查？
不是每次改 Skill 之後。那太頻繁了。
我的經驗是兩個信號：
信號一：密集開發期結束後。 連續多天高強度新增或修改 Skills，然後進入一段相對平靜的時期。這時候是做全局審查的好時機——你對細節還有記憶，但已經脫離了「衝刺模式」的慣性。
信號二：跨 Skill 的 bug 出現。 如果一個問題的根因跨越了兩個以上的 Skill（例如：A Skill 的引用指向 B Skill 已經刪除的段落），代表生態系的一致性在劣化。
收斂審查不是日常維護——它是一個有計畫的、系統性的全量 review。14 個 Skills、所有 Docs、所有交叉引用，一次看完。
花時間，但效果是累積的。做完一次之後，框架的內聚度明顯提升，後續的維護成本降低。
本文是「打造 AI Agent Skills 框架」系列的第 11/13 篇
← 上一篇：回歸測試與驗證閘門 → 下一篇：從個人工具到團隊基建