# 一支技能寫到五百行以上還不拆檔，Claude 不是讀不懂，是你先把它餵撐了 很多人寫技能有一個壞習慣：想到什麼就往 SKILL.md 裡塞，塞到幾百行還… · @swordBluesy · TwKit

@swordBluesy

# 一支技能寫到五百行以上還不拆檔，Claude 不是讀不懂，是你先把它餵撐了 很多人寫技能有一個壞習慣：想到什麼就往 SKILL.md 裡塞，塞到幾百行還覺得越完整越好。結果剛好相反，內容越長，Claude 越難一次抓住重點，真正需要的步驟反而被埋在文字堆裡。技能寫得長，不代表寫得好，常常只是代表還沒想清楚什麼該放前面、什麼該拆出去。 ## 設定欄位與多檔案結構的做法 先講必填欄位，只有兩個，但兩個都很嚴格。name 只能用小寫字母、數字與連字符，長度不能超過 64 個字元，而且必須和目錄名一致。名字和目錄對不起來，之後的查找與維護都會出問題，這是結構問題，不是風格問題。description 不能超過 1024 個字元，而且是整支技能裡最關鍵的欄位，因為啟動時 Claude 就是靠它來判斷要不要載入全文。描述寫不好，後面寫得再好都沒有出場機會。 再講選填欄位。allowed-tools 可以限制這支技能能用哪些工具，model 可以指定這支技能適合用哪個模型。這兩個欄位不是每一支技能都要填，填的時候要想清楚：限制工具是為了避免它亂動不該動的東西，指定模型是為了讓它在對的成本與能力下工作。沒有明確理由就不要亂填，限制寫錯了，技能反而會綁手綁腳。 好描述有一個檢驗標準：它要同時回答兩個問題，做什麼，以及何時用。只回答做什麼，Claude 知道這支技能是幹嘛的，卻不知道什麼時候該叫它；只回答何時用，Claude 知道時機，卻不知道它到底能做到什麼程度。兩個問題都要回答，描述才算完整。還有一點很實際：描述裡要放使用者真正會講的話。如果技能一直不觸發，很可能就是描述裡用的措辭，和使用者實際講的話對不上，這時候要補的，就是那些真實的說法，而不是更漂亮的術語。 接著是多檔案結構，也就是漸進披露。SKILL.md 最好控制在 500 行以內，超過就該拆。拆法是把東西分到三個目錄：scripts/ 放可以直接執行的腳本，references/ 放參考資料，assets/ 放其他資源。拆完還不夠，SKILL.md 裡要寫明什麼時候才去讀哪一個檔案。不是把檔案拆出去就叫漸進披露，告訴 Claude 在什麼條件下才打開哪個檔案，才叫漸進披露。 腳本有一項很划算的特性：腳本本身可以直接運行，只有執行後的輸出會佔用 token，腳本全文不需要先塞進對話裡。這就是為什麼重複的檢查、固定的流程適合寫成腳本，而不是寫成一大段文字讓 Claude 每次重新理解。 ## 一個可以照做的例子 假設你要做一支框架除錯技能，照做的結構是這樣： 第一步，目錄名與 name 保持一致，例如 framework-debug，描述同時寫清楚做什麼與何時用，例如在使用者遇到某個框架的錯誤、要求定位問題與修復方向時使用。第二步，SKILL.md 只寫流程骨架：先確認錯誤訊息，再定位相關檔案，再比對已知錯誤類型，最後給修復方向，總行數控制在 500 行以內。第三步，把錯誤對照表放進 references/，把檢查指令寫成 scripts/ 裡的腳本，並在 SKILL.md 裡寫明，只有遇到對照表裡那類錯誤時才打開對照表，只有需要執行檢查時才跑腳本。第四步，測試時故意用不同的說法描述同一個錯誤，看觸發是不是穩定，描述裡缺了哪種說法就補上哪種說法。 這個例子的好處是，主流程永遠很短，細節永遠在需要時才出現。Claude 不用一開始就讀完所有錯誤案例，也不會因為內容太長而抓錯重點。 ## S1哥觀點 技能設計最容易走偏的方向，就是把技能當成文件櫃。文件櫃是越滿越好，技能不是，技能是流程的入口。入口要短、要清楚、要一眼看得出該往哪裡走，細節要藏在後面，等需要時再拿出來。 爭論點在這裡：很多人覺得拆檔是多此一舉，直接寫在一份檔案裡比較省事。短期看確實省事，長期看卻是最貴的做法，因為每一次載入都要付 token 成本，每一次閱讀都要花注意力成本。拆檔不是為了好看，是為了讓 Claude 在對的時候只讀對的東西。你今天省下的那幾分鐘整理時間，以後會在每一次觸發時連本帶利還回去。 原文連結：https://anthropic.skilljar.com/introduction-to-agent-skills/434526 原文：Anthropic Academy（由 S1哥 編譯）

曝光 174 · 评论 2 · 点赞 2 · 书签 0