SKILL.md 超過 500 行就該拆

Skill 做順手之後，會出現一種囤積傾向：把員工手冊、整套格式範例、幾十個踩坑特例全塞進同一份 SKILL.md，覺得越完整越保險。

結果 AI 一載入這個技能，對話空間被塞滿，最關鍵的那幾條指令淹在裡面。它開始答非所問。你以為技能寫得不夠細，再補幾條，更糟。

官方文件對這件事有一個明確的數字：SKILL.md 主文件保持在 500 行以內，接近就拆。但比數字更重要的是拆的方法，什麼留、什麼移、移去哪。

主文件只留「為什麼」和「怎麼判斷」

官方文件的預設假設是一句話：Claude is already very smart。所以寫每一段之前問三個問題——它真的需要這段解釋嗎？我能不能假設它已經知道？這一段值得它佔的空間嗎？

他們給了一個對照。教它抽 PDF 文字，好的版本大約 50 個 token（用哪個套件、三行程式碼），差的版本大約 150 個（先解釋 PDF 是什麼、為什麼要用套件、怎麼安裝……）。差的版本不是錯，是把它本來就知道的事又講了一遍。

所以主文件該留的是它不知道的判斷原則。以週報為例，不要教它怎麼查 Google Drive，寫這段：「週報是給主管看的，挑資訊的標準不是我做了什麼，是主管需要知道嗎；卡點與下週動作排最前面。」有了這個原則，這週發生什麼變動它都能自己挑。這才是值得佔空間的東西。

官方還有一條我很認同：給預設，不要給選單。「你可以用 pypdf、或 pdfplumber、或 PyMuPDF、或……」是差的寫法；「用 pdfplumber；掃描檔需要 OCR 時改用 pdf2image」才對。選擇越多，它越容易挑錯。

格式進參考檔、動作進腳本

格式範例、術語表、特例清單，移到參考檔。週報需要一份一百行的排版範本，存成 reference.md，主文件只寫一句「輸出前對照 reference.md」。AI 平常不讀它，要輸出時才讀。兩條官方規矩：只准一層深，SKILL.md 指到 advanced.md、advanced.md 再指到 details.md，AI 讀到第二層常常只看前一百行就停，所有參考檔都要直接從 SKILL.md 連過去；超過 100 行的參考檔，開頭放目錄，它預覽時才知道整份有什麼、該跳到哪裡。

照做就對的動作，寫成腳本。「撈過去五天的 commit 並按時間排序」這種事，用自然語言講步驟，它可能撈成七天或漏一筆。寫成 scripts/fetch.sh，主文件寫「執行 scripts/fetch.sh，讀取輸出」。官方原句是只有腳本的輸出佔 token，腳本本身多長都不佔。這是三層裡最省的一層。

有一個容易混淆的地方要寫清楚：主文件裡要說明是「執行」還是「參考」。「Run fetch.sh to get commits」是執行，「See fetch.sh for the algorithm」是讀。多數情況你要的是前者。

動手做

有一份很肥的 SKILL.md，貼上去讓 AI 幫你拆三層：

下面是一份 SKILL.md。請拆成三層並輸出三份內容：
1. SKILL.md 新版：只留「為什麼、怎麼判斷、優先順序」和指路的句子，目標 100 行以內、最多 500 行。刪掉所有「AI 本來就知道」的解釋（套件是什麼、為什麼要用、怎麼安裝）。有選單的改成「預設用 X；例外情況用 Y」。
2. reference.md：格式範例、術語表、特例清單。超過 100 行的話開頭加目錄。
3. scripts/ 清單：列出哪些步驟是「照做就對、不需要判斷」的，各寫一行它該做什麼（我再請你寫實際腳本）。
最後標出：主文件裡哪幾句是「執行腳本」、哪幾句是「參考文件」，確認兩者沒混用。
SKILL.md：（貼上）

還沒寫 Skill 的，先看做第一個 Skill的範本。想知道自己的技能佔多少空間，Claude Code 打 /context，看 Skills 那一段。

拆對了的樣子：主文件 500 行以內，理想 100 行上下，每一段都是判斷原則；所有參考檔都直接從 SKILL.md 連過去，沒有第二層；超過 100 行的參考檔開頭有目錄；拿掉腳本的內容、只留執行指令，Skill 照常運作。

打開你最長的一份 Skill，只數一件事：有幾行是在解釋「AI 本來就知道的事」。這些行數就是你可以直接刪掉的。

500 行是官方的線，接近就拆，不要補。主文件只留它不知道的判斷原則，它本來就知道的事一行都不要。參考檔一層深、超過 100 行加目錄；腳本執行不讀，只有輸出佔空間。給預設，不給選單。

站內延伸

• 三層載入的原理 → 三層載入
• 拆完要怎麼測 → 評估先行
• 心法層怎麼寫 → 找方法AI 建 SOP

來源： Anthropic：Skill authoring best practices（500 行門檻、「Claude is already very smart」、50 vs 150 token 對照、參考檔一層深、超過 100 行加目錄、腳本只有輸出佔 token、給預設不給選單）。