設定與多檔案技能

設定與多檔案技能 · 4 分鐘

摘要逐字稿

本影片涵蓋讓技能更強大的進階技巧：關鍵的中繼資料欄位、如何撰寫能可靠觸發的描述、預先核准技能所需的工具，以及使用漸進式揭露在多個檔案中組織較大型的技能。您將學習如何在支援複雜使用案例的同時，保持技能的高效率。

重點整理

在 Claude Code 中，每個前置資料欄位都是選填的，只有 description 是建議填寫的。allowed-tools 和 model 是其中兩個最實用的附加欄位
一個好的描述回答兩個問題：這個技能做什麼？Claude 應該在什麼時候使用它？
allowed-tools 會在技能啟用期間預先核准所列出的工具，讓 Claude 可以在不詢問的情況下使用它們，而且不會限制 Claude 只能使用這些工具
漸進式揭露：將 SKILL.md 保持在 500 行以內，並連結到輔助檔案（參考資料、腳本、素材），Claude 只會在需要時才讀取這些檔案
腳本執行時不會將其內容載入上下文——只有輸出結果會消耗 token，讓上下文保持高效率

一個基本的技能只需要名稱和描述即可運作，但有幾種進階技巧可以讓您的技能在 Claude Code 中更加有效。讓我們來看看關鍵欄位、描述的最佳實踐、工具權限，以及如何組織較大型的技能。

技能中繼資料欄位

代理技能開放標準定義了 SKILL.md 前置資料中的核心欄位，而 Claude Code 則新增了許多自己的欄位，例如 model。在 Claude Code 中，所有欄位都是選填的，只有 description 是建議填寫的。以下四個是不錯的起點（其餘欄位列於前置資料參考文件中）：

name（選填）——識別您的技能。預設為目錄名稱。如果您將技能上傳到 Claude.ai 或 Claude API，則為必填，且僅限小寫字母、數字和連字號，最多 64 個字元。
description（建議）——告訴 Claude 何時使用該技能。如果您將技能上傳到 Claude.ai 或 Claude API，則為必填，且上限為 1,024 個字元。這是最重要的欄位，因為 Claude 會用它來進行比對。
allowed-tools（選填）——預先核准所列出的工具，讓 Claude 在技能啟用期間可以不經詢問許可即可使用它們。
model（選填）——指定該技能要使用哪個 Claude 模型。

撰寫有效的描述

明確地表達您的指示。如果有人告訴您「你的工作是協助處理文件」，您也不會知道該做什麼——Claude 的思考方式也是如此。

一個好的描述會回答兩個問題：

這個技能做什麼？
Claude 應該在什麼時候使用它？

如果您的技能沒有在您預期的時候觸發，請嘗試加入更多符合您實際提出請求方式的關鍵字。描述是 Claude 用來判斷技能是否相關的依據，因此用語非常重要。

使用 allowed-tools 預先核准工具

有時候，一個技能每次執行時都依賴同樣的幾個工具，而您不想每次呼叫都手動核准。allowed-tools 欄位會預先核准您所列出的工具，讓 Claude 在呼叫該技能的這一輪回合剩餘時間內，可以不經許可提示就使用它們。這項授權會在您傳送下一則訊息時清除。

編輯器中的 codebase-onboarding SKILL.md，allowed-tools 那一行已反白標示，如下方程式碼區塊所示。

在這個範例中，allowed-tools 欄位設定為 Read, Grep, Glob, Bash。當這個技能啟用時，Claude 可以不經詢問許可就使用這四個工具。它不會因此失去對其他任何功能的存取權：如果技能的指示導致 Claude 編輯或寫入檔案，那仍會像其他任何工具呼叫一樣，經過您正常的權限設定。要注意的一點是：單獨列出 Bash 會概括性地預先核准 shell 指令，因此請將其保留給您信任的技能，或將其限縮為特定模式，例如 Bash(git status *)。

yaml

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

如果您完全省略 allowed-tools，則不會預先核准任何工具，Claude 會對每個工具使用其正常的權限模型。若要反過來，在技能啟用期間移除工具，請使用另一個 Claude Code 前置資料欄位 disallowed-tools，它會從 Claude 可以使用的工具集中移除您所列出的工具。

漸進式揭露

技能與您的對話共用 Claude 的上下文視窗。當 Claude 啟用一個技能時，它會將該 SKILL.md 的內容載入上下文。但有時候您需要該技能所依賴的參考資料、範例或實用腳本。

把所有內容塞進一個 2,000 行的檔案會帶來兩個問題：它會佔用大量上下文視窗空間，而且維護起來也不有趣。

漸進式揭露可以解決這個問題。將必要的指示保留在 SKILL.md 中，並將詳細的參考資料放在另外的檔案中，讓 Claude 只在需要時才讀取。

開放標準建議以下列方式組織您的技能目錄：

scripts/——可執行程式碼
references/——額外的文件
assets/——圖片、範本或其他資料檔案

接著在 SKILL.md 中，連結到輔助檔案，並清楚說明何時要載入它們：

SKILL.md 的第 2 層和第 3 層區段連結到 architecture-guide.md 和 deep-dive-guide.md，僅在被要求時才載入。

在這個範例中，Claude 只有在有人詢問系統設計時，才會讀取 architecture-guide.md。如果他們問的是要在哪裡新增元件，它就永遠不會載入該檔案。這就像在上下文視窗中擁有一份目錄，而不是整份文件。

一個不錯的經驗法則是：將 SKILL.md 保持在 500 行以內。如果超過了這個限制，請考慮是否應該將內容拆分成另外的參考檔案。

有效率地使用腳本

您技能目錄中的腳本可以在不將其內容載入上下文的情況下執行。腳本會執行，而只有輸出結果會消耗 token。要在 SKILL.md 中包含的關鍵指示，是告訴 Claude 去執行該腳本，而不是讀取它。

這對以下情況特別有用：

環境驗證
需要保持一致性的資料轉換
以經過測試的程式碼來執行，會比生成的程式碼更可靠的操作

課程反思

想一想您想要建立的一個涉及多個檔案的技能。您會如何組織 SKILL.md 與輔助參考檔案之間的結構？
對於您團隊共用的技能，您會用 allowed-tools 預先核准哪些工具？又有哪些工具您寧可讓 Claude 持續詢問？

接下來呢

在下一課中，我們將把技能與其他可以自訂 Claude Code 的方式進行比較——CLAUDE.md、子代理、hooks 和 MCP 伺服器——讓您能夠為每種情況選擇正確的工具。