> ## Documentation Index > Fetch the complete documentation index at: https://felimet-hub.jmcores.com/llms.txt > Use this file to discover all available pages before exploring further. # 04-4 Skill：用途、格式、製作、references 與 scripts、各家差異 > Skill 把重複流程封裝成模型能依 description 自動叫用的程序。本單元從零製作一個實用 Skill，講解 description 寫法、漸進式揭露省 token 的策略，並對照各家等價機制。 export const LearnerPrimer = ({items = [], lang = "zh"}) => { const t = lang === "en" ? { title: "Before this unit, be honest with yourself", sub: "If you can't answer these, that gap is exactly what this unit closes." } : { title: "讀這個單元前，先誠實面對", sub: "這幾題答不出來，正是這個單元要替你補的洞。" }; const css = ` .lp-root{--lp-bg:#FAF7F1;--lp-surface:rgba(191,117,81,0.05);--lp-border:rgba(0,0,0,0.09);--lp-edge:rgba(191,117,81,0.42);--lp-text:#2b2722;--lp-dim:#6f6a62;--lp-accent:#bf7551;border:1px solid var(--lp-border);border-left:3px solid var(--lp-edge);border-radius:13px;background:var(--lp-bg);color:var(--lp-text);overflow:hidden;margin:1.25rem 0;} .dark .lp-root{--lp-bg:#1b1a18;--lp-surface:rgba(207,138,104,0.07);--lp-border:rgba(255,255,255,0.08);--lp-edge:rgba(207,138,104,0.5);--lp-text:#e7e3da;--lp-dim:#a8a299;--lp-accent:#cf8a68;} .lp-head{display:flex;align-items:center;gap:9px;padding:13px 18px 11px;border-bottom:1px solid var(--lp-border);background:var(--lp-surface);} .lp-ic{color:var(--lp-accent);flex-shrink:0;} .lp-htx{display:flex;flex-direction:column;gap:1px;min-width:0;} .lp-title{font-size:14px;font-weight:650;line-height:1.3;letter-spacing:.01em;} .lp-sub{font-size:12px;color:var(--lp-dim);line-height:1.4;} .lp-list{list-style:none;margin:0;padding:10px 18px 14px;display:flex;flex-direction:column;gap:0;} .lp-item{display:flex;align-items:baseline;gap:11px;padding:7px 0;font-size:14px;line-height:1.6;border-top:1px solid var(--lp-border);} .lp-item:first-child{border-top:none;} .lp-mark{flex-shrink:0;color:var(--lp-accent);font-size:13px;font-weight:700;line-height:1.55;font-variant-numeric:tabular-nums;opacity:.85;} .lp-q{flex:1 1 0;min-width:0;color:var(--lp-text);} @media (max-width:620px){.lp-head{padding:12px 14px 10px;}.lp-list{padding:8px 14px 12px;}} `; return
{t.title} {t.sub}
; }; **這個單元解決什麼問題** Skill 把重複流程封裝成模型能依 `description` 自動叫用的程序。它不只是一個 `SKILL.md`：依需求嚴謹度與適用範圍，會有 `references/` 放 few-shot 範本與規格、`scripts/` 放可執行工具腳本。本單元從零製作一個實用 Skill，講解 description 寫法、漸進式揭露（progressive disclosure）省 token 的策略，並對照各家等價機制。 ## 學習目標 * [ ] 寫一個結構正確的 `SKILL.md`，含 `description` 與必要的 frontmatter 欄位。 * [ ] 判斷何時建立 `references/` 子目錄（few-shot 範本、規格文件）與 `scripts/` 子目錄（可執行腳本）。 * [ ] 用漸進式揭露策略控制 token 消耗，讓複雜 Skill 不在每次叫用時傾倒全部內容。 * [ ] 判斷需求該做成 Skill、Rules 還是 Subagent，並說出判準。 * [ ] 對照各家工具中等價的 Skill 封裝機制，並知道主要差異點。 *** ## 1. Skill 是什麼 Skill 是一個放進 `~/.claude/skills//` 或 `.claude/skills//` 的目錄，內含 `SKILL.md`（必要）與可選的 `references/`、`scripts/`。Claude 在對話中**依 `description` 語意自動叫用**它，使用者也可以用 `/` 主動觸發 \[1]。 與 `CLAUDE.md` 的根本差別： | 維度 | `CLAUDE.md` | Skill | | ---- | ------------------- | -------------------------------- | | 載入時機 | 每次 session 啟動全量注入 | 只有在模型判斷相關、或使用者打 `/` 時才完整載入 | | 內容成本 | 每次 session 都付，跨整個對話 | 只有觸發的那一輪注入脈絡，沒觸發就零成本 | | 適合內容 | 通識、慣例、必守規則 | 程序、流程、依情境叫用的專業知識 | **Skill 是「依需求帶進來」的單元** `CLAUDE.md` 像放在桌上的桌面日曆，每天都在眼前。Skill 像抽屜裡的說明書，你要修水電才拿出來、修完放回去。把昂貴的內容從「每天付費」變成「用才付費」，就是 Skill 機制的本質價值。 **Skill 與 Command 已合併為同一底層** 截至 2026-06，Claude Code 的 `.claude/commands/.md` 與 `.claude/skills//SKILL.md` 在底層是同一個機制，都會產生 `/` 命令。差別在後者有目錄可放 `references/` 與 `scripts/`、前者只有單一檔 \[1]。本單元講後者（Skill），主動觸發的設計面見 [04-3](/code-agent/customization/commands)。 ## 2. 目錄結構 `SKILL.md` 是入口，其他檔案是輔助。`SKILL.md` 內用相對路徑引用 `reference.md` 等檔案時，Claude 會在需要時讀進來（見第 6 節漸進式揭露）。`scripts/` 內的腳本由 Claude 透過 Bash tool 叫用，不是被讀進 context。 ## 3. SKILL.md frontmatter 完整參考 ```yaml theme={null} --- name: my-skill description: What this skill does and when to use it when_to_use: Additional trigger phrases argument-hint: [issue-number] arguments: - issue disable-model-invocation: false user-invocable: true allowed-tools: Read Grep disallowed-tools: AskUserQuestion model: sonnet effort: high context: fork agent: Explore hooks: {} paths: - "src/api/**/*.{ts,tsx}" shell: bash --- ``` 逐欄位（截至 2026-06，依官方 Skills 章節 \[1]）： | 欄位 | 是否必填 | 用途 | | -------------------------- | ---- | ----------------------------------------------------------------------------- | | `name` | 選填 | 顯示名稱，預設是目錄名；只有 plugin 根目錄的 `SKILL.md` 會用它決定 command 名 | | `description` | 建議填 | 模型判斷是否叫用的依據。`description` + `when_to_use` 合計被截斷在 1,536 字元以省 context | | `when_to_use` | 選填 | 額外觸發情境說明、範例 prompt。可補 `description` 沒說的邊界 | | `argument-hint` | 選填 | 自動完成時顯示的參數提示，例如 `[issue-number]` 或 `[filename] [format]` | | `arguments` | 選填 | 命名位置參數，可為字串或 list。名稱依序對應位置 | | `disable-model-invocation` | 選填 | 設 `true` 禁止 Claude 自動叫用。預設 `false` | | `user-invocable` | 選填 | 設 `false` 從 `/` 選單隱藏，只讓 Claude 叫用。預設 `true` | | `allowed-tools` | 選填 | 啟用此 Skill 時免確認的工具清單（不會限制其他工具是否可用） | | `disallowed-tools` | 選填 | 啟用此 Skill 時從可用池中移除的工具 | | `model` | 選填 | 啟用此 Skill 時使用的模型，覆寫 session 模型，下一輪恢復 | | `effort` | 選填 | effort 等級（`low` / `medium` / `high` / `xhigh` / `max`），覆寫 session effort | | `context: fork` | 選填 | 設 `fork` 在獨立 subagent context 執行 | | `agent` | 選填 | `context: fork` 時使用的 subagent 類型（`Explore`、`Plan`、自訂） | | `hooks` | 選填 | 此 Skill 生命週期專屬的 hooks | | `paths` | 選填 | glob 模式，限定此 Skill 自動觸發的檔案範圍 | | `shell` | 選填 | 動態注入使用的 shell（`bash` 預設 / `powershell`，需 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`） | **`allowed-tools` 不會「拒絕」未列出的工具** `allowed-tools` 只是「免確認」清單，沒列的工具**還是能用**，受 session 權限設定管。要阻擋特定工具，請在 `settings.json` 的 deny 規則設 \[1]。 ## 4. 觸發控制：description、`when_to_use` 與 paths description 寫法決定模型會不會叫用你的 Skill。爛的 description 會誤觸或漏觸。 **描述寫法對照** 太泛，會誤觸： ```yaml theme={null} description: 幫我處理各種寫作任務 ``` 太窄，會漏觸： ```yaml theme={null} description: 幫我把週末研究日誌轉成 markdown ``` 剛好： ```yaml theme={null} description: 將對話中的研究觀察、心得、待辦事項整理為結構化 markdown 日誌。Use when the user says "log this", "記下來", "做個筆記", or wants to capture ideas from a long conversation into a single doc. when_to_use: 適用於想保存「不想現在處理、但要記下來」的想法。 ``` 觀察點：把觸發關鍵字（口語短語、英文同義）放進 `description`，模型比對時較容易命中。 `paths` 進一步把觸發條件收斂到「只在工作到某類檔案時」才叫用： ```yaml theme={null} --- description: API 設計規範檢查 paths: - "src/api/**/*.{ts,tsx}" --- ``` 模型只在編輯 `src/api/` 下的檔案時把這個 Skill 列為候選。 ## 5. 嚴謹度分級：Level 1 到 Level 3 ### Level 1：單檔 Skill 只有 `SKILL.md`，程序 50 行以內，無外部依賴。適合個人重複工作流的快速封裝。 ```yaml theme={null} --- description: 把目前 staged 的改動整理成 Conventional Commits 訊息 disable-model-invocation: true allowed-tools: Bash(git *) --- ## Staged diff !`git diff --cached` ## Recent style !`git log --oneline -5` ## Task Write a Conventional Commits message for the staged diff above. ``` ### Level 2：含 few-shot 的 Skill `SKILL.md` + `references/` 內的格式範例或規格文件。適合需要嚴格輸出格式（學術摘要、標準報告、合約條款）的場景。 `SKILL.md` 內引用： ```markdown theme={null} ## Instructions 1. Read the paper's abstract section. 2. Match the structure in `references/example-1.md`. 3. Follow section ordering in `references/style-guide.md`. 4. Write a 150-200 word summary. ``` ### Level 3：含可執行 scripts 的 Skill `SKILL.md` + `scripts/` 內的腳本（Python、Bash、Node.js 等）。適合需要真實計算、外部 API、或批次處理的任務，需同步考慮 `allowed-tools` 的安全設定。 `SKILL.md` 內用 `${CLAUDE_SKILL_DIR}` 引用同目錄的腳本（確保路徑解析與 skill 安裝位置無關）\[1]： ````yaml theme={null} --- description: 產生可互動式摺疊的程式碼樹狀視覺化。Use when exploring a new repo. allowed-tools: Bash(python3 *) --- Run: ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py . ``` ```` **從 Level 1 開始，按需要升級** 不要跳級。Level 1 寫完跑得起來後，如果你發現 Claude 輸出格式漂移，再加 few-shot（升級到 Level 2）；如果你發現需要跑計算或外部 API，再加 scripts（升級到 Level 3）。Level 3 寫得最重，但不一定適合每個工作流。 ## 6. 漸進式揭露（progressive disclosure） Skill 的核心 token 管理策略。`SKILL.md` 載入就進 context 並**在 session 內持續留存** \[1]，但**附屬檔案**（`references/`、`scripts/`）是按需載入的。意思是： * 簡單的 Skill：`SKILL.md` 全部進 context。 * 複雜的 Skill：把詳細規格、API 文件、few-shot 範例都放 `references/`，`SKILL.md` 只描述「何時該讀哪個 references/ 檔」，用 Markdown 連結引用。 好處：每次叫用 Skill 的 token 成本只跟「當下用到的 references/ 內容」成正比，跟 Skill 整體大小無關。 **漸進式揭露的 token 節省** 一個「產學術摘要」Skill，`SKILL.md` 30 行，內含 5 個 markdown 連結指向 `references/` 下 5 份各 80 行的格式範本。 **沒做漸進式揭露**：把 5 份範本全文塞進 `SKILL.md`，每次叫用 = 30 + 5 x 80 = 430 行。 **做漸進式揭露**：`SKILL.md` 30 行，5 個 markdown 連結，Claude 真的要看範例時才讀某一個 references/ 檔。平均每次叫用 = 30 + 80 = 110 行，省 75%。 在 200k context window 下，110 與 430 看起來都小。但乘上叫用次數與團隊規模，這是每月數百美元的成本差距。 ## 7. Skill 內容生命週期 Skill 觸發時，`SKILL.md` 渲染後的內容（`$ARGUMENTS` 已替換、`` !`cmd` `` 已執行）會以**單一訊息**形式進入 session 對話歷史，**在後續輪次中持續存在** \[1]。 `/compact` 摘要對話以釋放 context 時，Claude Code 會重新掛載（reattach）最近叫用過的 Skill 內容，每個 Skill 保留前 5,000 token，多個 Skill 共用 25,000 token 預算，從最近叫用的開始填。意思是：同一 session 叫用太多 Skill，較舊的會被完全丟掉 \[1]。 **Skill 看似「失效」不一定是丟失** 如果 Skill 叫用後幾輪你覺得它「沒在影響行為」，通常內容還在 context，只是模型在那一輪選擇了其他工具。強化 `description` 與指令措辭，或對關鍵行為加 Hook 強制 \[1]。 ## 8. 動態 context 注入：`` !`command` `` `SKILL.md` 內可用 `` !`` `` 在送進 Claude 之前先執行 shell，把輸出嵌入 \[1]： ```markdown theme={null} ## PR context - Diff: !`gh pr diff` - Comments: !`gh pr view --comments` - Files: !`gh pr diff --name-only` ## Your task Summarize this pull request in 3-5 bullets. ``` 規則： * 執行於**當前 shell**（macOS/Linux 預設 `bash`，Windows 可設 `shell: powershell`）。 * 輸出以純文字插入，不會再被重新解析為 `` !` `` 預留位。 * 內聯形式只認**行首**或緊接空白的 `!`，像 `` KEY=!`cmd` `` 的 `!` 不會觸發。 * 多行用 ` ```! ` fence 形式。 * 組織可在 settings 設 `"disableSkillShellExecution": true` 全面關閉（bundled 與 managed skill 不受影響）\[1]。 **動態注入 = 你的 shell 在跑** `` !`cmd` `` 是用你的本機 shell 執行，不是 sandbox。Skill 內容若由他人提供（共享 repo、plugin 市集），注入的指令就等於把 shell 控制權交給它。**永遠自己 review 過 `SKILL.md` 才 trust**。 ## 9. 工具對照 | 概念 | Anthropic Claude（主範本） | OpenAI Codex | Google Antigravity | GitHub Copilot | Cursor | | ------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | Skill 封裝單位 | `~/.claude/skills//SKILL.md` 或 `.claude/skills//SKILL.md` | `[[skills.config]]` 啟用控制 + 搜尋 `$HOME/.agents/skills/` 向上至 repo root（路徑是 `.agents/skills/`，非 `.codex/skills/`） | IDE 全域 `~/.gemini/config/skills/`；工作區一律 `.agents/skills/` | 個人層 `~/.copilot/skills//SKILL.md`、專案層 `.github/skills//SKILL.md`（同名覆寫個人層） | Rules for AI（`.cursorrules` 與 `.cursor/rules/`，性質偏規則而非 Skill）\[3] | | 自動叫用機制 | `description` 語意比對 + `paths` glob | 設定式，與 command / hook 整合 | `description` 語意比對，agent 依任務自動載入 | 設定式 | 規則式（依 frontmatter `globs`） | | Few-shot 附件目錄 | `references/`、其他子目錄依需求命名 | `references/` 等子目錄 | `references/`、`assets/` 子目錄 | 設定式 | 透過 `.mdc` 檔本身分段 | | 可執行腳本目錄 | `scripts/` | `scripts/` | `scripts/` | 不適用主流程 | 不適用 | | 工具權限收斂 | `allowed-tools` / `disallowed-tools` | 設定式 | 不適用 | 不適用 | 不適用 | | 指定叫用模型 | `model` frontmatter 欄位 | 設定式 | 不適用 | 不適用 | 不適用 | | 主動觸發方式 | `/` command | 與 slash command 整合 | agent 自動偵測 + `/` 選單 | 透過 `/` 選單 | 透過 `/` 選單 | | 跨工具共通標準 | 遵循 [Agent Skills](https://agentskills.io) 開放標準 | 部分遵循 | 部分遵循（`SKILL.md` / `skills.md`） | 部分遵循 | 不遵循 | **命名澄清與重要事實** * **Claude Code Skill 遵循 Agent Skills 開放標準**（[agentskills.io](https://agentskills.io)）\[1]。這標準是多家 AI 工具共用的，意味著你寫的 Skill 在合規的編輯器 / CLI 中應該能直接裝。 * **OpenAI Codex 的 Skill 機制**：以 `config.toml` 的 `[skills]` 區段設定，個人層 `~/.agents/skills//SKILL.md`、專案層 `/.agents/skills//SKILL.md`（trusted 才載入，以 `config.toml` 的 `[[skills.config]]` 啟用控制）。路徑是 `.agents/skills/`，非 `.codex/skills/`（依 developers.openai.com/codex/skills，截至 2026-06）。 * **GitHub Copilot 的「Skills」與「Copilot Extensions」是兩件事**：前者是本機 CLI 的 `SKILL.md` 機制，後者是 GitHub Marketplace 上的第三方擴充。本表只列前者。 * **Cursor** 沒有原生「Skill」機制，`.cursor/rules/*.mdc` 在功能上更接近 Claude 的 rules，`.cursorrules` 為單檔 rules 變體 \[3]。 ## 10. 與 Subagent 的配合 Skill 提供**程序**（步驟、判準、格式），Subagent 提供**獨立 context**（隔離執行環境）。兩者組合（見 [04-5](/code-agent/customization/subagents)）： ```yaml theme={null} --- name: deep-research description: 對某個主題做深入研究並回傳引用清單 context: fork agent: Explore --- Research $ARGUMENTS thoroughly: 1. Use Glob and Grep to find relevant files 2. Read and analyze the source code 3. Summarize findings with specific file references ``` 當設了 `context: fork` 時，Skill 內容變成 subagent 的 task prompt，subagent 在乾淨 context 裡執行，結果摘要回傳主對話 \[1]。 何時用 `context: fork`： * Skill 內要跑大量讀取、計算，不想污染主對話 context。 * 任務可平行化，每個 task 各自獨立。 * 主對話 context 已接近上限，需要隔離執行。 **`context: fork` 需要 Skill 內含「任務」** Skill 內容若只是「遵守這些 API 慣例」（規範式、沒有明確任務），`context: fork` 會讓 subagent 收到「慣例」但沒「要做什麼」，回傳空結果。`context: fork` 適合有明確步驟的程序型 Skill \[1]。 ## 自我檢核動手做 挑一個你每週重複 3 次以上的工作流，寫一份 30 行以內的 `SKILL.md`，含 `description` 與 2-3 個 markdown 步驟。放到 `~/.claude/skills//SKILL.md`，啟動 session 測試自動觸發與 `/` 手動觸發。 把上面那份升級，加 `references/example.md` 放一份完整 few-shot 範例，`SKILL.md` 內用 markdown 連結引用。比較有 / 無範例時 Claude 輸出品質。 在同一個工作階段裡叫用 Skill 多次，然後跑 `/context` 看 Skill 內容佔了多少 context。對照 `SKILL.md` 行數驗證「Skill 內容整個進 context」的設計事實。 寫兩個 Skill，一個用 `disable-model-invocation: true`、一個用 `user-invocable: false`，分別驗證使用者和模型的叫用權限。 ## 常見誤區 **反模式清單** * **`description` 寫太泛**（「幫我做各種任務」）：模型在無關情境誤觸，污染 context。縮到具體可辨識的觸發條件與關鍵字。 * **把所有規格文件塞進 `SKILL.md`**：每次叫用都傾倒全部 token。改用 `references/` 搭配漸進式揭露，內容只在需要時讀進。 * **跳過 Level 1 直接寫 Level 3**：過度工程化一個其實 30 行就能解決的需求。先驗證流程本身值得封裝，再決定是否升級。 * **不設 `allowed-tools` 就在 Level 3 跑 shell 腳本**：`SKILL.md` 內 `` !`cmd` `` 與 `scripts/` 內的執行呼叫都應該用 `allowed-tools` 明確允許的範圍。沒設時，Claude 用的是當前 session 權限，可能觸發大量確認或被完全擋下。 * **Skill 內含敏感資訊並 commit 進公開 repo**：API key、絕對路徑、內部 URL 都會被讀進 context 與上版控。需要動態注入的值應透過環境變數或動態 shell 取得，不寫死在 `SKILL.md` 內。 * **沒考慮 description 截斷**：每個 Skill 的 `description` + `when_to_use` 合計在 1,536 字元內才會完整進 skill 列表 \[1]。超過會被切，切掉的部分對模型不可見。 ## 自我檢核 **通過本單元的標準** 1. 你能寫出一個 frontmatter 完整、`description` 觸發條件精準的 `SKILL.md` 嗎？ 2. 你能判斷一個需求該走 Skill、Rules、Command 還是 Subagent 嗎？說出決策依據。 3. 你能用漸進式揭露策略，把一個 400 行的程序拆成 30 行 `SKILL.md` + `references/` 子目錄嗎？ 4. 你知道 Skill 內容進 context 後的生命週期嗎（`/compact` 行為、25k token 預算）？ ## 來源與延伸閱讀 事實主張依官方文件，快變動項標註截至 2026-05。
* \[1] Anthropic, "Extend Claude with skills," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) （截至 2026-06；含 frontmatter 完整參考、`references/` 與 `scripts/`、動態注入、`context: fork`、生命週期） * \[2] Anthropic, "Commands," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/commands](https://code.claude.com/docs/en/commands) （截至 2026-06；command 與 skill 合併機制） * \[3] Cursor, "Rules," cursor.com, 2026. \[Online]. Available: [https://cursor.com/docs/context/rules](https://cursor.com/docs/context/rules) （截至 2026-06；`.mdc` frontmatter 與 globs 機制） * \[4] Agent Skills Open Standard, "Agent Skills," 2026. \[Online]. Available: [https://agentskills.io](https://agentskills.io) （截至 2026-06；Claude Code 與其他 AI 工具共用的 Skill 封裝開放標準） * \[5] Agentic AI Foundation (Linux Foundation), "AGENTS.md," 2026. \[Online]. Available: [https://agents.md/](https://agents.md/) （截至 2026-06；跨工具共通專案規則檔標準）
* `CLAUDE.md` 與自動記憶見 [04-1 CLAUDE.md 與記憶檔](/code-agent/customization/claude-md-memory)。 * 規則檔 path-scoped 機制見 [04-2 rules](/code-agent/customization/rules)。 * 主動觸發 command 設計見 [04-3 Command](/code-agent/customization/commands)。 * Subagent 與 Skill 配合見 [04-5 Subagent](/code-agent/customization/subagents)。 * 上下文工程與 token 預算見 [01-4 上下文工程](/code-agent/foundations/context-engineering)。