Anthropic 的文件說得很清楚：SKILL.md 應該控制在 500 行以內。但他們自己的 docx 技能卻有 590 行。我在建立自己的 marketplace 的同時，逐一閱讀了 Anthropic 全部 17 項官方技能的 frontmatter。每一次都看到同樣的落差：文件說的是一回事，語料庫做的又是另一回事。而真正正確的，是語料庫。

以下是直接閱讀程式碼而非文件時，實際觀察到的結果。

Description 佔了技能的 90%

如果技能無法在正確的時機觸發，那它就毫無用處。而決定是否觸發的關鍵，不是 SKILL.md 的主體，而是 frontmatter 中的 description。Claude 會讀取可用技能清單（僅有名稱與描述），然後進行選擇。因此所有「何時使用」的資訊，都必須放在 description 裡，而不是主體。

反直覺的部分——Anthropic 在自己的 skill-creator 中也反覆強調：Claude 對技能的 under-trigger 遠多於 over-trigger。它只會在無法輕易處理任務時，才會查詢技能。「Read this PDF」永遠不會觸發 PDF 技能，即使 description 寫得再完美。因此文件明確指示：撰寫 description 時要稍微帶點推力。

在程式碼中就能看到這種做法：xlsx 技能寫著「Use this skill any time a spreadsheet file is the primary input or output」，pptx 則說「any time a .pptx is involved in any way」。完全沒有保留，積極推高觸發率，而非刻意壓低。

沒有人遵守的 500 行規則

「將 SKILL.md 控制在 500 行以內」是最常被引用的規則之一。但實際上 docx 有 590 行，而文件本身也補充「如果需要的話，可以再長一點」。其他技能的行數則介於 32 到 404 行之間。事實是：500 行只是一個目標，而不是硬性規定。

這條規則背後真正的原則不是長度，而是 context budget。SKILL.md 的主體會在每次觸發時載入。如果內容龐大是因為它包含了必要資訊，那可以超過。如果是因為拖著本來可以放在其他地方的細節，那才是問題。大小本身並不是罪過。

Progressive disclosure：以 scripts 為主，references 為輔

核心的技能模式是分階段載入：metadata（名稱 + 描述）永遠在上下文中，主體在觸發時載入，而資源（scripts/、references/）則只在需要時才載入。即使是 script，也可以在不被載入上下文的情況下執行。

但在語料庫中，17 個技能裡有 11 個只有單一 SKILL.md，完全沒有子資料夾。拆分不是常態，而是當領域需要時才採取的例外做法。而當真的拆分時，主要是拆成 scripts/：pdf、docx、xlsx、pptx 首先是確定性操作的 script 容器。references/（按需載入的文件）只出現在兩個技能中。教訓是：應該先把確定性的工作抽成可執行的程式碼，而不是先把散文抽到獨立檔案。

Anthropic 從不寫的「NOT for」

我在撰寫自己的技能時，會有系統地在 description 中加入「NOT for X」子句，以避免錯誤觸發。閱讀官方技能時，我發現：它們幾乎從不這麼做。它們的描述列出包含項目（「this includes…」），而非排除項目。

原因很簡單：它們的領域互不重疊。PDF 技能與 Excel 技能不可能被混淆，因此不需要排除，反而希望最大化觸發率。我的情況不同：我的技能彼此相關（審查 diff、發佈功能、結束分支是相鄰的任務）。「NOT for」讓我能在自己的技能之間進行區分。所以這不是通用規則，而是因應重疊而產生的做法。如果你的技能領域不互相競爭，就不要加入：你只會降低觸發率，而這是所有問題中最嚴重的。

他們實際上如何優化 description

官方 skill-creator 最有啟發性的部分，是它們不會憑感覺猜測好的 description，而是透過測量來決定。整個流程如下：

  • 20 個評估查詢：其中 8-10 個應該觸發，8-10 個不應該觸發。這些查詢要真實且混亂，就像真實使用者輸入的方式（檔案路徑、個人上下文、拼寫錯誤、小寫）。
  • 負面範例是接近但不觸發的案例，而不是明顯不相關的例子。「Write a fibonacci function」作為 PDF 技能的負面範例毫無意義。好的負面範例會與技能分享關鍵字，但需要額外條件才能判斷。
  • 每個查詢執行 3 次，以取得可靠的觸發率，然後進行 5 輪迭代改善。
  • 你根據 held-out test set 的分數來選擇 description（60% 訓練集、40% 測試集），避免對已知查詢過度擬合。

這是一個評估流程，而不是憑感覺。多數人會憑感覺寫 description 然後就結束，Anthropic 則把它當成產品來對待。

對照表：假設 vs 實務

17 個官方技能中，假設與實際做法的落差如下：

常見假設

官方語料庫的做法

SKILL.md 應控制在 500 行以內

docx 有 590 行，且文件補充「需要的話可以再長一點」

description 只要說明何時使用技能即可

必須帶有推力：真正的風險是 under-triggering

你應該拆分成 references/ 與 scripts/（progressive disclosure）

17 個技能中有 11 個是單一檔案；當拆分時，主要拆成 scripts/

你會在 description 中加入限制（「NOT for」）以避免錯誤觸發

幾乎從不寫入：領域明確區分，它們選擇最大化觸發率

好的 description 是憑感覺撰寫

它是經過測量的：20 個查詢、每個執行 3 次、5 輪迭代、在 held-out test set 上評分

要記住的重點

真正的教訓不在規則清單，而在落差本身。文件提供乾淨的啟發式方法，而語料庫顯示當現實需求出現時，專業人士如何彈性調整。閱讀 17 個技能比閱讀文件頁面更有幫助，因為你能看到真實的取捨：當內容需要時超過 500 行、三分之二的時間不進行拆分、積極推高觸發率而非限制它。

如果你只能記住一件事：風險不是你的技能觸發太多，而是它根本不會觸發。撰寫 description 時，要讓它容易被找到。

🧩 我的技能，可供安裝

我根據這些模式，從自己的真實工作流程中建立了一個 Claude Code 技能市集。請至 Skills 頁面 瀏覽與安裝，包含一個濃縮這些原則的 skill-builder 技能。若要設定 agent，請參閱 CLAUDE.md contexts。

常見問題

SKILL.md 應該有多少行？

目標是控制在 500 行以內，但這不是硬性規定：官方的 docx 技能有 590 行。重點是主體不要拖著應該放在 script 或 reference 檔案中的細節。如果必要內容需要更多篇幅，可以超過，然後在檔案中加入指向其他檔案的指標。

為什麼我的技能不會觸發？

幾乎都是 description 的問題。Claude 預設會 under-trigger，只會在非簡單任務時才查詢技能。讓 description 更具包容性且帶有「推力」（「use this skill whenever… even if the user doesn't say…」），並加入真實的觸發詞彙。同時請測試：單一步驟的任務永遠不會觸發技能，這是正常的。

我需要 references/ 與 scripts/ 資料夾嗎？

預設不需要：17 個官方技能中有 11 個只有單一 SKILL.md。當領域複雜時才進行拆分，而拆分後主要放入 scripts/ 來處理確定性工作（檔案操作、驗證）。references/ 只有在大型且多變的領域中才有存在的價值。

Skill、CLAUDE.md 或 hook？

Skill = 根據 description 在需要時觸發的能力。CLAUDE.md = 針對特定專案永遠載入的上下文。Hook = 由 harness 強制執行的確定性自動化事件，而非模型本身。如果是「永遠做 X」，那應該是 hook 或 CLAUDE.md，而不是 skill。