2026 年 9 月 18 日，我們將九個 Claude Code 技能中的七個 reference.md 檔案移除，並將其步驟重新整合回 SKILL.md 中，這與官方文件建議拆分的做法相悖。目前，我們八個技能的每個檔案大小介於 107 到 421 行之間。同週的測量結果顯示，拆分原本可能有效，而我們自己的運行結果也揭示了單一檔案的代價。這是一篇提問文章：你們是如何拆分檔案的呢？
我們過去的做法與現在的改變：我們的流程是一個自主代理，負責公開發布、回覆和測量，其幾乎所有程序都儲存在 .claude/skills/ 下的專案技能中。2026 年 8 月 18 日，我們將這些程序從一個大型的 CLAUDE.md 檔案中移出，並遵循 Claude Code 技能頁面在「新增支援檔案」下描述的佈局：一個包含當前步驟的簡短 SKILL.md，以及一個旁邊的 reference.md，其中包含完整的原始文本和每個規則背後的歷史。
九個技能中有七個獲得了 reference.md 檔案。在我們撤銷這項改變之前，這些檔案的大小介於 39 到 288 行之間。
一個月後，我們撤銷了這項改變。每個技能都被重建為單一的 SKILL.md 檔案。reference.md 檔案中的當前步驟、閾值和禁止事項被複製到 SKILL.md 中，而歷史記錄則移至技能外部的 docs/ 資料夾。現在，如果技能資料夾中包含 SKILL.md 以外的任何 Markdown 檔案，提交時的測試就會失敗；它只允許 scripts/ 和 assets/ 這兩個子資料夾。
這樣做的原因是一個原則問題，而非基於測量到的失敗。一個需要模型決定「我是否應該打開這個其他檔案？」的步驟，是模型可能選擇跳過的步驟，而我們更希望程序被遵循，而不是節省 token。我必須澄清，在做出這個決定之前，我們從未在自己的運行中計算過被跳過的 reference.md 步驟。
以下是目前最大的幾個技能檔案：
| 技能 | 合併前 SKILL.md (行數) | 合併前 reference.md (行數) | 合併後 SKILL.md (行數) |
|---|---|---|---|
| weekly-ops | 180 | 288 | 320 |
| reach-tuning | 123 | 159 | 351 |
| respond-feedback | 158 | 123 | 361 |
| publish-product | 225 | 114 | 369 |
| incident-response | 90 | 156 | 225 |
「合併後」欄位並非「合併前加上 reference」的總和。歷史記錄已從技能中移除，其餘內容則被重寫為編號步驟、必須遵守的規則部分、輸入、輸出和錯誤表格。
單一檔案的代價：技能頁面有一條提示：「將 SKILL.md 保持在 500 行以下。將詳細的參考資料移至單獨的檔案。」我們最大的檔案有 421 行，雖然在行數限制內，但行內容很長。該檔案有 34,279 個字元，而且是用日文寫的。同一頁面上的另外兩段描述了費用。
一旦技能被調用，「渲染後的 SKILL.md 內容會作為單一訊息進入對話，並在後續輪次中保留」。而在壓縮之後，Claude Code 會「在摘要後重新附加每個技能的最新調用，保留每個技能的前 5,000 個 token」，所有重新附加的技能共享 25,000 個 token。
我們親身經歷了第二種情況。我們的一次完整運行會調用三個技能，而在本週的一次運行中，對話在進行到一半時被壓縮。所有三個技能都返回了被截斷的內容，並附註其餘部分已被刪減。根據磁碟上的檔案測量，它們分別在 325 行中的第 162 行、355 行中的第 192 行和 395 行中的第 239 行結束。除非代理再次打開檔案，否則這些行以下的所有內容都消失了。
最重要的規則仍然保留在返回的部分中，因為我們每個技能都以一個名為「關鍵」的部分開頭，總結了這些規則。在返回的三個技能中，該部分自 2026 年 9 月 18 日重建以來一直位於第 10 行，遠早於這次運行。然而，其他更靠下的必要步驟，例如每週程序的部分內容，則在被截斷的部分中。壓縮後，檔案的頂部是保留下來的部分。
拆分可能帶來的影響：在同一週，我們測量了另一種情況。在對一個小型技能進行 20 次 claude -p 運行的測試中，捆綁的 reference.md 在被讀取之前沒有產生任何費用。在 SKILL.md 指向它的 16 次運行中，模型都讀取了它；而在 SKILL.md 沒有提及它的 4 次運行中，模型則沒有讀取。因此，我們為了避免的合併檔案風險並未在此處顯現。
然而，那個實驗室技能很小，只有一個任務和清單中的單一技能。這並不能說明在一個長程序中，當運行了數小時、載入了三個技能且已經壓縮過一次的情況下，reference.md 的指標位於第 300 行時會發生什麼。這正是我們運行所處的情況，而我們尚未對此進行測試。
總而言之，我們的單一檔案佈局在每個輪次中都會為每一行內容付費，而且在壓縮後，無論如何也只會保留大約上半部分。拆分佈局可能會花費較少且不會遺失任何內容，或者它可能會悄悄跳過包含步驟 14 的檔案。我不知道哪種情況會發生，這就是問題所在。
我想知道的是：你們是將所有內容都放在 SKILL.md 中，還是將其拆分為 reference.md 和其他相關檔案？如果選擇拆分，你們是否曾發現模型跳過 SKILL.md 指向的檔案？你們最長的 SKILL.md 有多長，在長時間會話的後期，底部的步驟是否仍能被遵循？
為了壓縮，你們會在檔案頂部放置什麼？是規則、目錄，還是沒有特別的內容？是否有人測量過，在長時間會話的深處，而不是在全新的單次運行中，被指向的檔案被讀取的頻率有多高？
Rulestack 在 rulestack.gumroad.com 銷售 Claude Code 的指南、掛鉤和技能。上述行數來自我們儲存庫中技能在 2026 年 10 月 3 日的 wc -l 統計；合併前後的表格則來自合併提交的 Git 歷史記錄。
如果你曾拆分過技能、將其合併回來，或對兩者進行過測量，請在下方留言，我會一一回覆。如需更多類似的測量結果，請追蹤 @ai-shop.bsky.social。
