如果我的 Skill 內容真的很複雜，硬要塞進 500 行以內會不會反而犧牲說明的完整性？
這個擔心背後其實有個誤解：500 行限制的是本體，不是整個 Skill 能傳達的資訊總量。完整性不需要犧牲，只需要重新分配——把「Claude 每次觸發都一定會用到」的核心邏輯留在本體，把「只有特定情境才需要」的細節移到延伸檔案。
實務上，複雜的 Skill 通常代表它涵蓋了多種使用情境，這種情況下更應該問的是：這些情境是不是描述得太籠統、其實可以拆成幾個各自專精、各自觸發的 Skill？一個 Skill 只做一件事，通常會比一個嘗試涵蓋所有情境的巨型 Skill 觸發得更準確，也更容易維護。
多個檔案的 Skill，資料夾結構應該怎麼安排？
常見的慣例是每個 Skill 一個獨立資料夾，內含 SKILL.md 作為主入口，搭配 scripts/（可執行的程式碼，通常設計成小型 CLI 工具）、references/（補充性的背景資料，例如結構描述、速查表）、assets/（範本或輸出時要用到的靜態檔案）幾個子目錄，依內容性質分類。
這個結構背後的邏輯跟三層披露機制是一致的：SKILL.md 負責導覽和高層流程說明，各子目錄放的是「需要時才讀」或「需要時才執行」的內容。連結深度建議只做一層——SKILL.md 直接連到 references/ 底下的檔案，不要讓 references/ 裡的檔案又連到更深一層的檔案，否則會讓 Claude 為了查一個細節要連續跳轉好幾次，反而違背了漸進式披露原本想節省的成本。
description 欄位除了寫清楚功能，還有什麼實務上容易忽略的重點？
最容易被忽略的是：description 應該同時包含「這個 Skill 做什麼」和「什麼情況該用它」兩個部分，而不只是功能描述。舉例來說，只寫「處理 Git commit 訊息」比較籠統，寫成「當使用者要為已 staged 的變更撰寫 commit 訊息時使用」則同時涵蓋了功能與觸發情境，Claude 比對使用者請求時能更準確判斷。
另一個容易忽略的重點是具體關鍵字。使用者實際打字時很少會用開發文件式的正式用語，反而更常用口語化的說法。如果 description 裡能涵蓋使用者實際可能講出口的字詞和情境描述，觸發準確率會比只用術語堆疊的描述明顯提高。這也是為什麼一個 Skill 只做一件事會比較好觸發——功能單一，description 才能寫得夠具體。
我現在手上已經有好幾個超過 500 行的 Skill.md 在用，需要立刻回頭重寫嗎？
不需要恐慌性地立刻全部重寫，但值得排入優先順序去檢視。判斷是否值得優先處理的訊號是：這個 Skill 觸發的頻率高不高、以及觸發時是否經常伴隨著其他任務同時進行。如果一個超長的 Skill 觸發頻率很高，代表它每次都在稀釋掉其他上下文內容，優先度應該最高；如果是很少觸發的 Skill，即使超過 500 行，急迫性也相對較低。
重寫時建議的順序是：先把 description 檢查一遍，確認觸發判斷本身沒問題；接著把本體內容按「核心邏輯」與「情境性細節」分類，情境性細節先移到一個暫時的 reference.md；最後再回頭確認本體是否已經自然瘦身到合理範圍。與其一次全面重構，這種漸進式的拆分方式風險更低，也更容易在每一步都確認 Skill 仍然正常運作。
寫第一個 Skill 的時候，最容易犯的錯誤不是寫得太短，而是寫得太長——把所有可能用到的細節、每一種例外情況、每一段參考資料全部塞進同一個 Skill.md，想著「反正寫進去總沒有壞處」。但這個直覺剛好和 Skill 的設計原理相反。
Anthropic 官方文件對 SKILL.md 的長度給出了明確門檻：本體建議控制在 500 行以內，超過就應該拆分到獨立檔案。這不是隨口給的建議數字，背後對應的是 Skill 架構本身的三層漸進式披露（Progressive Disclosure）機制——理解這三層怎麼運作，才會知道「該寫多長」這個問題其實問錯了方向。
Skill 的載入過程分成三個階段，每個階段讀取的內容量差異很大。第一層是啟動時，Claude 只讀取每個 Skill 的 YAML frontmatter——也就是 name 和 description 兩個欄位，這一層每個 Skill 只佔用幾十個 token，即使系統裝了幾十個 Skill，啟動時的負擔也很小。
第二層是觸發時：當使用者的請求跟某個 Skill 的 description 描述的情境相符，Claude 才會把該 Skill 完整的 SKILL.md 本體讀進上下文。這一層才是「500 行」門檻要管的範圍——本體越長，觸發後一次性湧入的內容越多，稀釋掉上下文裡其他真正相關的資訊。
第三層是延伸讀取：如果 SKILL.md 內部連結了其他檔案（例如 forms.md、reference.md），Claude 只有在實際需要那部分細節時才會去讀，不會因為 Skill 被觸發就把所有延伸檔案一次讀完。
這裡最容易被誤解的地方：500 行限制的是 SKILL.md 本體，不是這個 Skill 能包含的知識總量上限。以官方文件舉例的 PDF 處理 Skill 為例，SKILL.md 本體只保留核心邏輯與最常用的操作方式，表單填寫這種較少用到、細節又多的內容，被移到獨立的 forms.md，只有使用者實際要求填表單時，Claude 才會去讀那份檔案。
換句話說，一個 Skill 底下能承載的知識總量幾乎沒有上限，限制的只是「每次觸發時，第一波湧進上下文的份量」。把這個機制想成一本組織良好的手冊——先給目錄，再給對應章節，最後才是附錄裡的詳細規格，讀者不需要為了查一個小細節，把整本書從頭讀到尾。
三層披露的第一層完全靠 description 欄位運作——Claude 決定要不要觸發某個 Skill，比對的依據就是這段描述文字跟使用者請求的語意是否相符。如果 description 寫得籠統（例如只寫「處理 PDF 相關工作」），Claude 很可能在使用者明明需要這個 Skill 的情境下，判斷不出該觸發它；反過來，如果寫得夠具體、包含使用者實際可能講出口的關鍵字和情境描述，觸發的準確率會明顯提高。
這也是為什麼「SKILL.md 該寫多長」不是第一個該問的問題——如果 description 寫得不夠精準，本體再怎麼精簡都沒有意義，因為 Claude 根本不會走到讀取本體那一步。
實務上的判斷原則很直接：SKILL.md 本體應該只放高層邏輯與最常用的操作步驟，任何一個段落如果篇幅超過幾百字、或是屬於「大部分情況用不到，但少數情況需要完整細節」的內容（例如特定錯誤碼的處理方式、進階參數設定），就是拆到獨立檔案的訊號。拆分後的檔案建議只做一層連結深度，避免 Claude 為了查一個細節，要連續跳轉好幾層文件。
下次動手寫 SKILL.md 之前，先把 description 寫到位——具體到能讓 Claude 一眼判斷「這個請求該不該觸發我」。接著把本體內容控制在核心邏輯與高頻操作範圍內，任何細節性、低頻率但份量大的內容，果斷移到獨立檔案。500 行不是硬性天花板，而是一個提醒：如果寫到這個量還沒拆檔案，代表本體已經開始承擔它不該承擔的角色。