技能

「Skills」（技能）是可重複使用、以檔案系統為基礎的資源，能為您的代理程式提供特定領域的專業知識：工作流程、上下文與最佳實務，將通用型代理程式轉變為專家。您新增的每個技能都會對工作階段的「context window」（上下文視窗）產生少量成本，加入有助於模型使用該技能的指示與中繼資料。請參閱 Agent Skills 概覽以深入了解。

技能可透過兩種方式提供給您的代理程式：透過代理程式的 skills 陣列附加，或從掛載於工作階段的 GitHub 儲存庫載入。附加的技能分為兩種類型。所有技能的運作方式都相同：當技能與任務相關時，您的代理程式會自動呼叫它們。

• 預先建置的 Anthropic 技能： 常見的文件任務，例如 PowerPoint、Excel、Word 與 PDF 處理（pptx、xlsx、docx、pdf）。
• 自訂技能： 由您撰寫並上傳至工作區的技能。

若要了解如何撰寫自訂技能，請參閱 Agent Skills 與技能撰寫最佳實務。若要將自訂技能上傳至您的工作區，請參閱建立自訂技能。



建立自訂技能

自訂技能是一個包含 SKILL.md 檔案及任何支援檔案的目錄，以 zip 壓縮檔或個別檔案的形式上傳至您的工作區。建立技能會回傳 skill_* ID，供您在將其附加到代理程式時參照。Anthropic 預先建置的技能已在每個工作區中提供，不需要此步驟。若只想使用預先建置的技能，請跳至將技能附加到代理程式。

Skills API 不需要 beta 標頭。仍然傳送 anthropic-beta: skills-2025-10-02 的請求會繼續運作，並回傳先前的回應欄位。

這些範例省略了選用的 display_name 欄位，因此技能的顯示名稱會從 SKILL.md 中的 name 欄位衍生而來。明確指定的 display_name 最多可為 255 個字元，且在您的工作區內不需要是唯一的。

ant skills create \
  --file example_skill.zip

若要列出、擷取、刪除自訂技能及管理其版本，請參閱管理自訂技能。如需完整的請求與回應結構描述，請參閱 Create Skill API 參考文件。技能套件會直接上傳至 Skills API，而非透過 Files API。



將技能附加到代理程式

在建立代理程式時附加技能。每個工作階段最多支援 500 個技能，以工作階段中所有代理程式去除重複後的集合計算（請參閱多代理程式協作）。

skills 陣列中的每個項目使用下列欄位：

ant beta:agents create < agent.yaml

name: Financial Analyst
model: claude-opus-5
system: You are a financial analysis agent.
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest



從 GitHub 儲存庫載入技能

技能也可以存放在您的程式碼庫中。當工作階段透過 github_repository 資源掛載儲存庫時，系統會在工作階段啟動時掃描儲存庫根目錄的 .claude/skills 目錄，在其中找到的每個技能都會提供給代理程式使用。不需要上傳，也不需要在代理程式的 skills 陣列中加入項目。代理程式會看到每個已探索到的技能在沙箱中的名稱、說明與路徑，並在任務相符時讀取該技能的 SKILL.md，包括技能隨附的任何指令碼與資源。探索仰賴代理程式工具集中代理程式的 read 工具，該工具預設為啟用；停用 read 的代理程式不會載入儲存庫技能。

探索只會在 .claude/skills/<skill-name>/SKILL.md 這個確切位置尋找技能，也就是儲存庫根目錄下一層目錄深度：

• your-repo/
  • .claude/
    • skills/
      • code-review/
        • SKILL.md
      • release-process/
        • SKILL.md
        • scripts/
          • run_checks.sh
  • src/

不符合此配置的位置不會在工作階段啟動時被探索到：

• .claude/skills/SKILL.md：外層沒有技能目錄的 SKILL.md
• .claude/skills/tools/code-review/SKILL.md：巢狀深度超過一層目錄
• skills/code-review/SKILL.md：位於 .claude 之外的 skills 目錄

位於儲存庫其他位置的 .claude/skills 目錄（例如套件子目錄內）不會在工作階段啟動時公告；當代理程式讀取該子樹下的檔案時，這些技能仍可能浮現。

儲存庫技能使用與您上傳的自訂技能相同的 SKILL.md 格式。如需格式與撰寫指引，請參閱 Agent Skills 與技能撰寫最佳實務。

若要從儲存庫載入技能，請建立一個掛載該儲存庫的工作階段。這與存取 GitHub 中所示的請求相同；mount_path 為選用，預設為 /workspace/<repo-name>：

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)

對於私有儲存庫，資源的 authorization_token 必須具有該儲存庫的存取權。這與任何儲存庫掛載所使用的個人存取權杖流程相同；請參閱存取 GitHub。

已探索到的技能會依循儲存庫的簽出狀態：若資源有設定 checkout 分支或提交，則使用該分支或提交，否則使用儲存庫的預設分支。掃描只會在工作階段啟動時執行一次。工作階段進行中推送的提交不會被納入；若要載入更新後的技能，請啟動新的工作階段。

儲存庫技能可與透過代理程式 skills 陣列附加的技能並行運作。如果儲存庫技能與某個附加的技能同名，或與另一個已掛載儲存庫中的技能同名，兩者皆可使用；每個技能都會以各自的路徑公告。



後續步驟