技能

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

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

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

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

建立自訂技能

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

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

ant apply skills/pr-summary

---
name: pr-summary
description: Summarize a pull request's changes and risks in the team's review format.
---

# PR summary

List what changed, why, and anything a reviewer should look at closely, in three short sections.

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

將技能附加到代理程式

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

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

ant apply agent.md

---
name: Financial Analyst
model: claude-opus-5-5
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest
---

You are a financial analysis agent.

從 GitHub 儲存庫載入技能

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

探索會在確切的 .claude/skills//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/：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "github_repository",
            "url": "https://github.com/org/repo",
            "mount_path": "/workspace/repo",
            "authorization_token": "ghp_your_github_token",
        },
    ],
)

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

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

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

後續步驟