最難寫下來的，通常是你最熟的事
做過幾年軟體開發或資料工程之後，腦袋裡會累積不少近似「條件反射」的判斷。
收到 on-call alert，你知道先看哪個 dashboard、進哪個 log group、用什麼關鍵字過濾。接手別人的 data pipeline，你先找 null check 和 schema validation，再讀主要邏輯。新需求一來，你很快就能估出大概是一天還是一週的工作量。
這些判斷幾乎不需要思考。但如果有人問你：「能把你這套判斷寫成文件讓新人照做嗎？」你大概會愣一下。
知識管理把這種「知道怎麼做，卻很難完整說明」的內容稱為隱性知識（Tacit Knowledge）。在野中郁次郎提出的 SECI 模型裡，「外化」（Externalization）指的是把隱性知識轉成能被表達、傳遞的顯性知識。
AI 輔助開發工具普及後，Skill 成了另一種承載這些知識的方法。
Skill 是一份能被 AI 發現、載入並照步驟執行的工作流程規格。它當然也是文件，但比一般 README 或 prompt template 多了觸發條件、判斷分支、限制與驗收方式。對工程師來說，可以把它理解成一道讓 AI 呼叫工程判斷的介面。
接下來要處理的，就是怎麼把腦中的經驗整理成一份可靠的 Skill。
Skill 如何載入：先判斷相關，再讀取細節
在開始寫之前，先理解 AI 怎麼「使用」你的 Skill，否則你會在錯誤的地方花力氣。
AI 通常不會一開始就把 Skill 的所有檔案全讀進 context，而是採用漸進式揭露（Progressive Disclosure）：先看足以判斷相關性的資訊，確認任務需要後，再載入細節。
第一層：Frontmatter 裡的 description。每次對話 AI 都能看見，token 消耗極小，但它要靠這幾句話判斷「現在的任務跟這個 Skill 有關嗎」。這是決定生死的篩選器。
第二層：SKILL.md 內文。AI 判定這個 Skill 跟當前任務相關後，才會把 body 載入 context。你的完整指令、判斷邏輯、限制規則都在這裡。
第三層：references/ 目錄裡的額外資源。API 文件、範本檔、範例程式碼。AI 有明確需要時才會往裡面翻。
可以把 description 想成 README 首段、body 想成 API 文件，references 則像 examples/ 目錄。
所以 frontmatter 沒寫好，後面的內容很可能根本不會被載入。
第一步：用真實情境把經驗挖出來
常見的錯誤是跳過經驗萃取，直接開始寫 SKILL.md。
結果寫出來的東西不是太抽象（「分析問題並提出解決方案」），就是太瑣碎（逐行列出十五個 CLI 指令卻沒說什麼時候該用哪個）。
比較可靠的做法，是先回到真實工作場景，從「如果 AI 要接手，它必須知道什麼」的角度，回顧至少三到五個實際案例。
打開你最近一個月的工作筆記、Slack 對話、或 PR review 紀錄。找出你重複做過的工作。如果你能在三個不同案例裡，找到相同的判斷模式，那就是一個值得封裝成 Skill 的候選項。
接著用 AI 做結構化訪談。先別叫它直接寫 Skill，請它從案例歸納規則：
我最近處理了這三個 data pipeline 故障案例：
[案例 A：上游 schema 變更導致下游 null pointer]
[案例 B：Kafka lag 激增導致處理延遲]
[案例 C：S3 權限更新後 ETL job 靜默失敗]
請從這三個案例歸納出：
1. 我判斷問題類型的依據是什麼
2. 我排查的固定順序或優先級
3. 我在什麼條件下會跳過某些步驟
4. 我絕對不會做的事（例如不手動改 production table）
AI 擅長從具體案例找共通模式，卻無法憑空知道你的偏好。素材要由你提供，歸納工作再交給它。
幾輪來回後，你手上會有一份粗糙但真實的流程文字稿。這不是最終的 Skill，但它是你最真實的原材料。
第二步：把原材料壓進工程結構
有了文字稿，接下來是結構化。這一步決定 AI 能不能按規格執行你的流程，而不是自由發揮。
從 data engineering 的角度，我把它想成 schema design——你定義的不是資料欄位，而是 AI 處理任務時的「判斷欄位」和「轉換規則」。
一份好 Skill 的 body 通常由以下幾塊組成（不是每次都全用，依複雜度選配）：
決策分支：讓 AI 根據輸入走不同路
你的工作流程裡，有些路口是要做判斷的。同一類型的問題，來源不同、嚴重程度不同，處理方式可能完全不同。
沒有決策分支的 Skill，AI 每次都走預設路徑——通常就是它認為「最安全」的那條，但不見得是你需要的那條。
設計決策分支時，保持節點在四個以內。每多一個判斷層，AI 的執行準確度都會下降。這跟你設計 data pipeline 的 branching logic 一樣——分支太多等於沒有分支。
步驟流程：寫得像 runbook，不像說明書
執行步驟要寫成 AI 能直接操作的指令，不是概念描述。
差的寫法：「檢查資料品質」。好的寫法：「對目標表格的最近一批資料執行 null count，若超過 5% 則停止後續步驟並回報」。
把每一步想成 runbook 裡的操作條目——你在凌晨三點被叫醒、腦袋只清醒一半的時候，還能照著做的那種清晰度。AI 也需要這種清晰度。
禁止清單：你的血淚教訓
禁止清單往往是 Skill 裡很有價值的一段。
缺少明確限制時，AI 會用通用做法補足空白；工程現場的風險，往往就藏在這些預設行為裡。因此，除了寫「要做什麼」，也要把不能跨過的邊界列清楚。
每一條 NEVER 背後應該對應一個你實際遇過的問題。例如：
- NEVER 在沒有 dry-run 的情況下修改 production 資源
- NEVER 假設上游 schema 不會變，必須做 defensive parsing
- NEVER 把 credential 寫進程式碼或 log 中
這些規則若來自實際事故或近失事件，會比通用安全口號更有用。AI 不知道你的組織曾在哪裡出過問題，這部分只能由你補上。
完工驗收條件：什麼叫「做完了」
沒有完工條件的 Skill，AI 不知道該在哪裡停下來。它可能過早結束，也可能在不需要的地方繼續鑽牛角尖。
好的完工條件應該是可機械驗證的，例如：
- 所有相關測試通過
- 輸出檔案符合指定 schema
- git diff 範圍在預期之內
- 無 lint error 或 type error
這跟 data pipeline 的 quality gate 完全一樣的思路——你不會讓一條沒通過 data validation 的管線上線，也不應該讓一個沒通過驗收的 Skill 執行結果被採用。
第三步：用 Frontmatter 劃清觸發邊界
回到漸進式揭露的第一層。frontmatter 裡的 description 是 AI 判斷「要不要載入這個 Skill」的唯一依據。
很多人把 description 當成欄位填一下就好。然而，它的本質更接近你在設計 API 時寫的 endpoint 路由規則——它定義的是什麼 request 應該被 route 到這裡。
一個設計得好的 description 同時包含三個維度：
正向觸發條件（什麼情況應用這個 Skill）：
USE FOR: data pipeline 故障診斷、ETL job 靜默失敗排查、
上下游 schema 不一致的問題定位
反向排除條件（什麼情況不要用）：
DO NOT USE FOR: 本地開發環境除錯、SQL 查詢優化、
新 pipeline 的架構設計（改用 pipeline-design skill）
語意觸發詞（使用者可能的說法）：
Trigger words: pipeline broken, ETL failed, data missing,
schema mismatch, job stuck, 資料遺失, 管線故障
反向排除條件很容易被忽略。沒有邊界的 Skill 像缺少 content-type 檢查的 API endpoint，什麼 request 都會進來，誤觸發也會跟著增加。
第四步：用 AI 生成初稿，再用你的經驗修正
有了結構化的素材，現在可以請 AI 幫你組裝第一版 SKILL.md。
給 AI 的 prompt 應該包含完整的上下文，而不只是一句「幫我寫個 Skill」：
我要建立一個 Agent Skill，用途是 [一句話描述]。
以下是我從實際案例歸納出的素材：
## 觸發時機
[你從第一步得到的觸發條件]
## 不適用情境
[明確列出不該觸發的場景]
## 判斷分支
[你整理好的決策節點]
## 執行步驟
[你的 step-by-step 流程]
## 紅線
[你的 NEVER 清單]
## 完成標準
[可驗證的完工條件]
請依照 SKILL.md 格式輸出，frontmatter 包含 name 與 description，
description 要同時有正向觸發詞和 DO NOT USE FOR 排除詞。
AI 生成的初稿常見兩個問題：
- 步驟描述太通用。AI 會把你具體場景的邏輯抽象化，例如把「檢查 Kafka consumer group lag」泛化成「檢查訊息佇列延遲」，反而失去了精確性。
- 夾帶 AI 本來就會做的事。「確保程式碼可以編譯」「使用正確的 Markdown 格式」這類敘述完全是冗餘——AI 不需要你提醒它做基本的事，寫這些等於在浪費 context 空間。
初稿拿到手之後，你要做的修正工作：
- 把被泛化的步驟改回你的具體場景用語
- 刪除所有 AI 本來就會做的敘述
- 確認每一條 NEVER 都對應一個你刻骨銘心的真實事件
檢查 Skill 裡的每一行：「拿掉之後，AI 的輸出會變差嗎？」如果不會，就刪掉。值得保留的是 AI 自己推不出來、只有你知道的判斷。多餘內容會占用 token，也會讓重要規則更難被看見。
第五步：分三個方向測試 Skill
你不會把一條 data pipeline 寫完就直接上線跑。Skill 也一樣。
測試 Skill 有三個不同的驗證維度，每個維度抓的是不同類型的問題：
觸發邊界測試
你的 description 精準嗎？準備三組對話：
- 正面：明確屬於這個 Skill 對應的場景。例如「幫我查 pipeline X 為什麼今天早上沒跑」
- 同義改寫：換個說法，語意相同。例如「ETL job X 的 output table 今天是空的，什麼狀況」
- 不相關：語意完全不同。例如「幫我寫一個 Python 函式讀 CSV」
如果前兩組沒觸發，description 太窄。如果第三組也觸發了，description 太廣。
流程合規測試
觸發之後，AI 有沒有真的按照你寫的步驟走？
重點不是看 AI 是否完成了任務——而是看它有沒有跳步驟。AI 模型看到不夠具體的步驟描述時，傾向自行判斷重要性，然後略過它認為不重要的。
跳步驟幾乎都指向同一個根因：那個步驟的指令不夠具體。把「檢查相關設定」改成「讀取 config.yaml 中的 source_table 和 target_table 欄位，確認兩邊 schema 版本一致」，跳步驟的問題通常就解了。
有 Skill vs 無 Skill 對比測試
同一個任務，分別在有 Skill 和沒有 Skill 的條件下各跑一次。比較輸出品質。
如果差別不顯著，代表你的 Skill 沒有真正在引導 AI——可能是因為 body 裡的內容大部分是 AI 本來就會做的事。這時候需要回頭重新提煉，增加真正源自你獨特經驗的部分。
把每次偏差寫回規格
如果你做過 data pipeline 的開發，你知道一件事：第一版永遠不是最終版。
Schema 會演進，上游會改格式，業務邏輯會調整。你的 pipeline 因此需要持續維護。Skill 完全一樣。
每次 AI 執行你的 Skill 之後，觀察結果跟你預期的差距在哪。不要只接受或拒絕輸出——回去看是哪一條規則沒寫清楚，把它修正。
幾個常見的迭代情境：
AI 不觸發 Skill：通常是 description 裡缺乏足夠的關鍵詞覆蓋。一個有效的 debug 方法——直接問 AI「你什麼時候會使用這個 Skill？」，它會引述 description 回答，你馬上能看出缺口在哪。
AI 觸發太頻繁：需要加反向排除條件。明確告訴它「這不是你的事，遇到 X 場景請用另一個 Skill」。
AI 跑完但結果不對：步驟描敘不夠具體，或判斷分支遺漏了一種情境。
AI 做了不該做的事：NEVER 清單需要擴充，補上你剛發現的新邊界案例。
每次修正，都是把原本只存在腦中的判斷補回規格。
分類思維：不是所有 Skill 都在產出程式碼
工程經驗不只有寫程式碼這一種。你的判斷力在不同環節有不同形態，對應的 Skill 設計也該不同。
陪伴思考型：引導你釐清思路，不直接產出。例如需求評審——AI 不該直接開始實作，而是先問你一系列問題。這類 Skill 的特徵是輸入開放、輸出是決策方向而非程式碼檔案、工具需求最低。
規劃型：把模糊需求轉成可執行計畫。它的輸出通常是結構化文件（task list、architecture decision record）。這類 Skill 需要你的 schema 設計經驗——什麼欄位必填、什麼欄位有預設值、什麼格式是上下游能接受的。
執行型：拿到明確規格就開工。寫測試、做 code review、跑部署流程。這類 Skill 的步驟最詳細、NEVER 清單和完工條件最嚴格，因為執行型的錯誤成本最高。
你在開始寫之前，先判斷你的 Skill 屬於哪一種。不同類型的結構重心不同——把規劃型 Skill 寫成執行型的步驟會太死板，把執行型 Skill 寫成思考型的開放式引導會失控。
寫完之後，還要能被驗證
建立 Skill 的檔案門檻不高：一個資料夾、一個 Markdown 檔案。難的是把工作流程說清楚，包括何時觸發、怎麼判斷、哪些事不能做，以及什麼條件才算完成。
Anthropic 在 Agent 系統設計文章裡強調，工具介面的設計和工具本身同樣重要。SKILL.md 就是你和 AI 之間的介面，也應該像程式碼一樣接受版本控制與測試。
一份能用的 Skill，應該可以版本控制、測試並持續修正。先從三到五個真實案例開始，把那些「不用想就知道」的判斷寫成條件，再用實際任務驗證它是否真的改變了 AI 的行為。