YAML Frontmatter

YAML Frontmatter 是什麼，跟一般的檔案內容有什麼不同？

YAML Frontmatter 是放在 Markdown 檔案最開頭的一個獨立區塊，用一對 --- 標記包起來，裡面用 YAML 格式寫著關於這個檔案的中繼資料（metadata），例如名稱、描述、版本、授權方式等。它跟檔案主體內容的差別在於：主體是要給讀者（或 Claude）閱讀理解的實質內容，Frontmatter 則是描述「這份內容是什麼」的結構化標籤，通常不會直接顯示給使用者看，而是被系統用來做索引、篩選、或決定要不要載入。

在 Claude Code 的 Skill 檔案裡，Frontmatter 只有開頭那一段 --- 是檔案的第一行時才會被正確解析；如果前面多了其他文字，整份檔案會被當成沒有 Frontmatter，全部內容都被當作一般說明文字處理。

YAML Frontmatter 為什麼存在，解決了什麼問題？

如果沒有 Frontmatter，系統要判斷一個檔案「是什麼」，唯一的辦法就是把整份內容讀進來分析——這在檔案數量少的時候還可以接受，但當一個系統可能同時掛載幾十個 Skill 時，每次啟動都要把每個 Skill 的完整內容讀一遍才能判斷相不相關，會消耗掉大量不必要的上下文空間。

Frontmatter 解決的正是這個問題：把「這是什麼、什麼時候該用」濃縮成幾十個 token 的中繼資料，讓系統在啟動階段只需要讀這一小段就能做出初步判斷，真正需要用到某個 Skill 時才去讀取完整本體。這也是 Skill 架構所謂三層漸進式披露的第一層——metadata 永遠載入，本體視觸發情況載入，延伸檔案視實際需要載入。

YAML Frontmatter 實際運作起來是什麼樣子？

以 Claude Code 的 Skill 標準來說，Frontmatter 規範裡真正被官方標準承認的欄位只有六個：必填的 name（小寫、連字號分隔）與 description（說明這個 Skill 做什麼、什麼時候該用），以及選填的 license、compatibility、metadata、allowed-tools。Claude Code 系統啟動時只讀取每個 Skill 的 name 和 description，這一步消耗的 token 數極小，即使同時掛載大量 Skill 也不會造成明顯負擔。

在這六個欄位裡，description 這個欄位的重要性遠高於其他欄位——它是系統決定要不要觸發某個 Skill 的唯一比對依據，如果寫得不夠具體，即使本體內容再完整，Claude 也可能因為判斷不出相關性而從未觸發它。這也是為什麼多數教學都會特別強調：Frontmatter 裡最值得花心思打磨的，往往不是欄位數量多寡，而是這一句 description 寫得夠不夠精準。

了解 YAML Frontmatter 的運作邏輯，對我實際寫 Skill 有什麼影響？

最直接的影響是寫作順序：應該先把 description 寫到位——具體到能讓 Claude 一眼判斷「這個請求該不該觸發我」——再去思考本體內容要放什麼，而不是反過來。很多新手容易把力氣花在本體寫得多詳細，卻忽略了如果 description 判斷不準，Claude 根本不會走到讀本體那一步，本體寫得再好都沒有用武之地。

另一個實務上容易踩到的坑，是把開頭那對 --- 標記寫錯位置——例如前面多打了一行空白或註解，導致 Frontmatter 解析失敗、整份檔案被當成純文字內容處理。這種情況下 Skill 通常不會直接報錯，而是安靜地失效（沒有 name 或無法被辨識），寫完 Skill 後最好實際測試看看 Claude 會不會在對的情境下觸發它，而不是只靠肉眼檢查格式。