Skill 目錄結構怎麼組織：scripts、references、assets 與漸進式披露，腳本怎麼寫

本文根據 Agent Skills 開放規範（agentskills.io）的《Specification》《Using scripts in skills》《Best practices for skill creators》整理，資料核對於 2026-10-11。SKILL.md 本身的寫法見《SKILL.md 怎麼寫》。

適用於誰

• 搜「skill 目錄結構」「claude skill 目錄結構」「skill 如何調用腳本」「skill python 腳本」的人；
• SKILL.md 越寫越長，想拆分又不知道怎麼拆的人；
• 想讓 Skill 帶上腳本、模板，讓智能體直接執行而不是每次重寫的人。

結論先說

1. 一個 Skill 就是一個文件夾，必須有 SKILL.md，另外約定了三個可選目錄：scripts/（可執行代碼）、references/（按需閱讀的文檔）、assets/（模板和靜態資源）。
2. 加載分三層：啟動時只讀所有 Skill 的名稱和描述（每個約 100 token）；啟用時讀整份 SKILL.md；其餘文件用到時才讀。這就是「漸進式披露」。
3. SKILL.md 控制在 500 行以內，詳細資料拆到單獨的文件，並寫清「什麼情況下讀哪個文件」。
4. 文件引用用相對路徑、只引一層，不要讓參考文件再去引用別的參考文件。
5. 給智能體用的腳本不能有交互式輸入。這是硬性要求：智能體在非交互的終端裏運行，等待輸入的腳本會一直卡住。

一、官方約定的目錄結構

skill-name/
├── SKILL.md          # 必需：元數據 + 說明
├── scripts/          # 可選：可執行代碼
├── references/       # 可選：文檔
├── assets/           # 可選：模板、資源
└── ...               # 其他文件或目錄

規範說明，除了 SKILL.md 之外可以放任何文件和目錄，上面三個只是推薦的組織方式。

二、漸進式披露：三層各放什麼

規範原文給出的三層：

1. 元數據（約 100 token）：name 和 description，啟動時為所有 Skill 加載；
2. 說明（建議少於 5000 token）：SKILL.md 正文，啟用該 Skill 時加載；
3. 資源（按需）：scripts/、references/、assets/ 裏的文件，只在需要時加載。

由此得出的寫法：

• 每次執行都要用到的核心步驟，放 SKILL.md；
• 只在某些情況下才需要的細節（某個接口的錯誤碼錶、某一類文檔的特殊處理），放 references/；
• 「注意事項」留在 SKILL.md 裏。官方的理由是：這類不明顯的坑，智能體在遇到之前並不知道自己需要去讀，放進單獨文件很可能讀不到。

拆出去的文件要告訴智能體何時去讀。官方的對比很清楚：

• 有用的寫法：「如果接口返回非 200 狀態碼，閱讀 references/api-errors.md」；
• 沒用的寫法：「詳見 references/ 目錄」。

三、怎麼引用文件

在 SKILL.md 裏引用其他文件時，用從 Skill 根目錄出發的相對路徑：

markdown
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

規範的兩條要求：

• 只引用一層：從 SKILL.md 直接指向目標文件；
• 避免層層嵌套的引用鏈：A 引 B、B 再引 C，智能體很容易半路停下。

代碼塊裏的腳本路徑同樣相對於 Skill 根目錄，因為智能體是在那裏執行命令的；這條約定在 references/*.md 裏也適用。

四、不寫腳本：直接調用現成的包

如果已有的工具包就能完成任務，可以在 SKILL.md 裏直接寫命令，不需要 scripts/ 目錄。官方列出了幾種能在運行時自動解決依賴的方式：

官方示例（npx 與 pipx）：

bash
npx eslint@9 --fix .
pipx run 'black==24.10.0' .

三條建議：

• 鎖定版本，這樣命令的行為不會隨時間變化；
• 在 SKILL.md 裏寫明前置條件（如「需要 Node.js 18+」），運行環境層面的要求寫進 frontmatter 的 compatibility 字段；
• 命令複雜到很難一次寫對時，改成腳本。只帶幾個參數的調用適合直接寫命令。

五、把腳本放進 scripts/

先在 SKILL.md 裏列出有哪些腳本，讓智能體知道它們存在：

markdown
## Available scripts

- **`scripts/validate.sh`** — Validates configuration files
- **`scripts/process.py`** — Processes input data

再在流程裏寫明怎麼運行：

bash
bash scripts/validate.sh "$INPUT_FILE"
python3 scripts/process.py --input results.json

讓腳本自帶依賴聲明。 這樣智能體一條命令就能運行，不需要單獨的清單文件和安裝步驟。Python 用 PEP 723 的內聯元數據，官方示例：

python
# /// script
# dependencies = [
#   "beautifulsoup4",
# ]
# ///

from bs4 import BeautifulSoup

然後用 uv run scripts/extract.py 運行，uv 會創建隔離環境並安裝聲明的依賴。官方還給了 Deno（npm: 導入）、Bun（導入路徑裏寫版本）、Ruby（bundler/inline）的同類寫法。

什麼時候值得寫腳本。 官方的判斷方法是看執行記錄：如果智能體每次都在重新實現同一段邏輯（畫圖、解析某種格式、校驗輸出），就把它寫成一個經過驗證的腳本放進 scripts/。

六、給智能體用的腳本，接口怎麼設計

智能體靠讀標準輸出和標準錯誤來決定下一步，所以腳本的接口設計直接影響成功率。

1. 不要有交互式提示（硬性要求）。 所有輸入通過命令行參數、環境變量或標準輸入傳入。缺參數時應該立刻報錯並給出用法，而不是停下來等輸入：

Error: --env is required. Options: development, staging, production.
Usage: python scripts/deploy.py --env staging --tag v1.2.3

2. 用 --help 說明用法。 這是智能體了解腳本接口的主要途徑，寫清簡介、參數和示例，保持簡短。

3. 報錯訊息要能指導下一步。 說明哪裏錯了、期望什麼、收到了什麼。「Error: invalid input」這種資訊只會白白浪費一輪。

4. 輸出用結構化格式。 JSON、CSV、TSV 優於對齊的純文本。數據走標準輸出，進度和警告走標準錯誤。

5. 其他建議

• 冪等：智能體可能重試，「不存在則創建」比「重複就報錯」安全；
• 對含糊的輸入直接拒絕，不要猜；
• 有破壞性的操作提供 --dry-run 預覽，並考慮要求顯式的確認參數；
• 不同失敗類型用不同的退出碼，並寫進 --help；
• 控制輸出體積：很多工具會截斷過長的輸出，預設只輸出摘要，需要更多時再用參數翻頁。

常見問題

Q：三個目錄名必須叫這個嗎？

規範把它們稱為「推薦的約定」，不是強制。但沿用約定的名字，別人和其他工具更容易看懂。

Q：腳本會自動執行嗎？

不會無條件執行。智能體按 SKILL.md 的說明決定何時運行，能否運行還要看所用工具的權限設定。也正因為 Skill 可以帶腳本，安裝別人的 Skill 前要先看一遍 scripts/ 裏的內容，見《MCP 伺服器怎麼選、裝之前怎麼審》裏的同類檢查思路。

Q：模板放 SKILL.md 裏還是 assets/ 裏？

短模板直接寫在 SKILL.md；較長的、或只在某些情況下才用的模板放 assets/，在 SKILL.md 裏引用，這樣不用時不佔上下文。

Q：參考文件可以很多嗎？

可以，按需加載意味着沒被讀到的文件不佔上下文。前提是 SKILL.md 裏寫清了每個文件對應什麼情況。

參考資料

• Specification（Agent Skills 官方規範）：https://agentskills.io/specification
• Using scripts in skills：https://agentskills.io/skill-creation/using-scripts
• Best practices for skill creators：https://agentskills.io/skill-creation/best-practices