花十小時打磨的 Skill，遠勝過十分鐘速成的那個

我以為寫一個 Skill 就是把 SKILL.md 丟進資料夾、收工。十分鐘搞定，沒什麼大不了。這套做法用得挺順，直到我發現同樣的錯誤在每次呼叫時一再重演，而且我根本沒辦法判斷這個 Skill 到底有沒有照我的意思在運作。

後來，Anthropic 負責開發 Claude Code 的工程師 Thariq 發了一篇文，把我對這件事的看法整個翻轉：「把 Skill 用好，本身就是一種技術問題。」

這句話讓我久久無法忘懷，因為它說中了我觀察到的現象。隨便寫一個 markdown 檔和好好架構一個 Skill 資料夾之間的差距，不只是理論上的，它真實地反映在輸出品質上。

Skill 是一個資料夾，不是一個檔案

最常見的誤解，是把 Skill 等同於一個 SKILL.md 檔案。實際上，Skill 是一個資料夾，裡面包含腳本、參考程式碼、設定檔，以及將它們串接起來的 markdown 檔。

Anthropic 內部採用他們稱為「漸進式揭露」的做法。他們不把所有東西塞進一個提示詞，而是將檔案分層排列，讓 Claude 在需要的時候才讀取需要的內容。references/api.md 存放函式簽名，Claude 可以按需取用；assets/ 目錄放輸出範本，這樣提示詞就不必描述格式細節；驗證腳本讓 Claude 在回傳結果前能先自我檢查。

打開 skill-creator repo，你可以直接看到這個原則的實踐。agents/、references/、scripts/ 這些目錄和 SKILL.md 並排放置。而那個用來建立 Skill 的工具，本身也是以 Skill 的形式建構的。

Gotchas 比提示詞本文更重要

Thariq 說，Gotchas 區塊是整個 Skill 裡「資訊密度最高的內容」。不是主要指示，不是範例，而是 Gotchas。

這和我的親身經驗完全吻合。我寫了一個沒有 Gotchas 區塊的 Skill，結果同一個錯誤連踩三次。就在我補上一行說明那個具體失敗模式之後，問題就再也沒出現過。

道理其實很直觀。提示詞本文裡大多數的內容，Claude 早就知道了。告訴它怎麼寫 TypeScript 或格式化 JSON，不過是在重述它本來就處理得很好的事。但告訴它在你的特定情境下不該做什麼，才是真正新的資訊。

Thariq 文章裡有幾個我覺得很有用的原則：不要陳述顯而易見的事，因為重複的指示反而會降低效果；不要用過度細節的步驟來限制 Claude，那會讓它失去應變能力；還有一點，description 欄位不是給人讀的說明文件，它是 Claude 用來判斷何時觸發這個 Skill 的依據。

Skill Creator 讓「感覺有效」變成「驗證有效」

兩週前的 Skill Creator 更新，改變了我對 Skill 品質的思考方式。你可以定義測試提示詞、設定預期結果，工具會幫你驗證 Skill 是否真的產出正確結果。這就是針對提示詞的單元測試。

我對一個用了好幾週的 Skill 加上了評估項目。有兩個我以為一定過關的測試案例，馬上就失敗了。修改的幅度不大，但套用之後，輸出品質明顯提升了。

這裡有個實用的分類方式，把 Skill 分成兩種類型。「能力提升型 Skill」是教 Claude 做它本來做不好的事；「偏好編碼型 Skill」是把團隊特定的工作流程或規範固定下來。前者有天然的有效期，因為模型進步遲早會讓它變得多餘；後者只要工作流程存在就會持續有價值。評估機制能幫你抓住能力提升型 Skill 變成死重的那個時間點。

這套工具支援基準測試模式，可以在模型更新時追蹤通過率和 token 用量；多代理平行執行，避免測試過程中的上下文污染；以及一個比較代理，能在不知道是哪個版本的情況下，對有無 Skill 的輸出進行盲測 A/B 比較。

複利效應

綜觀我看過的數百個 Skill、自己維護的幾十個，有一個規律始終成立：Skill 的價值來自持續迭代，而不是第一稿的好壞。

資料夾結構決定你如何塑造 Claude 的上下文視窗。Gotchas 把你的失敗轉化為可重用的知識。評估機制幫你確認那些知識是否仍然有效。

寫一個 SKILL.md 要十分鐘。從真實失敗中整理 Gotchas、建立評估案例、加入驗證腳本，大概要十小時。但這個投入在 Skill 每次執行時都在回報你。今晚就設定一個。到明天早上，它已經替你完成了你本來得自己做的事。