Progressive Disclosure

漸進式揭露是什麼，跟把所有內容塞進同一份文件有什麼不同？

漸進式揭露指的是把一份說明文件的內容分層安排：最上層是一份精簡的主檔案（例如 Skill.md），裡面只放最基本的操作方式跟一份「路標」——指向其他延伸檔案的連結；真正詳細的內容（例如進階功能、完整 API 參考、大量範例）分別放在各自獨立的檔案裡，Claude 只有在真的需要那部分資訊時，才會去讀取對應的延伸檔案。

跟把所有內容塞進同一份文件最大的不同在於「什麼時候佔用上下文」。如果把所有細節都寫進同一份主檔案，不管當下任務用不用得到,這些內容一旦被載入就會全部佔用上下文空間；漸進式揭露則讓延伸檔案在沒被讀取之前完全不消耗任何 token,只有主檔案的精簡摘要會先進到上下文裡,真正需要細節時才臨時去讀取那份對應的檔案。

漸進式揭露為什麼被需要，解決了什麼問題？

上下文視窗是一種共用資源——一個 Skill 的內容要跟系統提示、對話紀錄、其他 Skill 的中繼資料、使用者的實際請求一起分享同一個有限的空間。如果每個 Skill 都把完整的細節內容（API 參考、大量範例、進階功能說明）全部塞進主檔案，當使用者同時可能觸發多個 Skill、或單一 Skill 內容本身就很龐大時，會很快把上下文空間耗盡，擠壓掉真正該用來處理當下任務的空間。

漸進式揭露解決的正是這個資源分配問題:它讓「內容存在」跟「內容佔用上下文」這兩件事分開——一份 Skill 可以打包非常完整、詳盡的參考資料，只要沒被讀取,這些資料就不會消耗任何 token。這代表撰寫者不需要在「內容夠不夠完整」跟「會不會佔用太多上下文」之間妥協，兩者可以同時兼顧，因為完整性由延伸檔案負責，精簡度由主檔案負責。

漸進式揭露實際上怎麼運作，有哪些常見的組織方式？

最基本的運作機制,是 Claude 一開始只會預先載入所有 Skill 的名稱與描述（中繼資料),完整的 SKILL.md 內容要等這個 Skill 真的被判定相關時才會讀取,而 SKILL.md 裡引用的其他延伸檔案,則要等 Claude 真的需要那部分資訊時才會另外去讀取——這個機制靠的是 Claude 在具備檔案系統存取能力的執行環境裡,用類似指令列的方式按需讀取檔案。

常見的組織方式有三種:第一種是「高層次指南加參考文件」,主檔案給快速上手的做法,進階功能或完整 API 各自獨立成延伸檔案;第二種是「依領域分類」,適合橫跨多個主題的 Skill,例如按財務、業務、產品分別建立獨立的參考檔案,使用者問業務問題時只會讀到業務相關的檔案,不會連帶載入財務或產品的內容;第三種是「條件式細節」,主檔案先給基本做法,只有在使用者的需求真的涉及進階情境（例如需要追蹤修訂或處理複雜格式）時才連到對應的延伸檔案。無論哪一種,有一條共通的實務建議是:延伸檔案的引用層級盡量只從主檔案直接連出去一層,不要讓延伸檔案裡面又連到更深一層的檔案,因為 Claude 在讀取巢狀過深的引用時,可能會用預覽的方式只讀取部分內容,反而拿到不完整的資訊。

漸進式揭露對我有什麼實際影響，寫 Skill 時該怎麼判斷內容該放主檔案還是延伸檔案？

一個簡單的判斷準則是:如果一段內容是「幾乎每次觸發這個 Skill 都會用到」的基本操作,放進主檔案;如果是「只有特定情境才會用到」的進階功能、完整參考、大量範例,拆成獨立的延伸檔案,並在主檔案裡留一句話加連結指向它。實務上官方建議主檔案本文盡量控制在 500 行以內,一旦接近這個篇幅,就是該考慮把部分內容拆出去的訊號。

另一個實用的判斷方式,是問自己:「如果使用者這次的任務完全用不到某段內容,這段內容有沒有辦法完全不被載入?」如果答案是「沒辦法,因為它跟主檔案寫在一起」,代表這段內容值得拆出去;如果它已經是一份獨立檔案、只有需要時才會被讀取,代表這部分已經做到了漸進式揭露該有的效果。對於篇幅較長的延伸檔案(超過一百行),額外在檔案開頭加一份目錄,能讓 Claude 就算只預覽部分內容,也能掌握這份檔案完整涵蓋了哪些範圍。