技能

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

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

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

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



建立自訂技能

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

Skills API 不需要 beta 標頭。cURL 範例仍會傳送 anthropic-beta: skills-2025-10-02，而 CLI 和 SDK 的 beta 命令會自動新增該標頭；包含此標頭的請求仍可正常運作，無需變更。

這些範例省略了選用的 display_title 欄位，因此技能的標題會從 SKILL.md 衍生。明確傳遞的 display_title 在您工作區的自訂技能中必須是唯一的。

ant beta: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 陣列附加的技能並行運作。如果儲存庫技能與附加的技能或另一個掛載儲存庫的技能同名，兩者皆可使用；每個技能都會以其各自的路徑宣告。



後續步驟