MessagesSkills

透過 API 使用 Agent Skills

了解如何透過 API 使用 Agent Skills 來擴展 Claude 的能力。

Agent Skills 透過組織化的指令、腳本和資源資料夾來擴展 Claude 的能力。本指南將向您展示如何透過 Claude API 使用預建和自訂的 Skills。

快速連結

在 API 中開始使用 Agent Skills

了解如何在 10 分鐘內使用 Agent Skills 透過 Claude API 建立文件。

Skill 撰寫最佳實務

了解如何撰寫有效的 Skills，讓 Claude 能夠成功發現並使用。

概述

Skills 透過程式碼執行工具與 Messages API 整合。無論是使用由 Anthropic 管理的預建 Skills，還是您自行上傳的自訂 Skills，整合方式都完全相同：兩者都需要程式碼執行，並使用相同的 container 結構。

使用 Skills

無論來源為何，Skills 在 Messages API 中的整合方式都相同。您在 container 參數中指定 Skills，包含 skill_id、type 和選用的 version，它們會在程式碼執行環境中運行。

您可以使用來自兩種來源的 Skills：

面向	Anthropic Skills	自訂 Skills
Type 值	`anthropic`	`custom`
Skill ID	簡短名稱：`pptx`、`xlsx`、`docx`、`pdf`	自動產生：`skill_01AbCdEfGhIjKlMnOpQrStUv`
版本格式	基於日期：`20251013` 或 `latest`	版本 ID：`skver_01AbCdEfGhIjKlMnOpQrStUv` 或 `latest`
管理方式	由 Anthropic 預建並維護	透過 Skills API 上傳和管理
可用性	所有使用者皆可使用	僅限您的工作區私有

兩種 Skill 來源都會由 List Skills 端點回傳（使用 source 參數進行篩選）。整合方式和執行環境完全相同，唯一的差異在於 Skills 的來源以及管理方式。

先決條件

要使用 Skills，您需要：

來自 Claude Console 的 Claude API 金鑰
在您的請求中啟用**程式碼執行工具**

Skills 在 Claude API 上已正式推出，無論是 Skills API 還是 Messages 請求中的 container.skills，都不需要 anthropic-beta 標頭。本指南中的範例仍會傳送 skills-2025-10-02 beta 標頭（在 Messages 請求中另加 code-execution-2025-08-25），並使用 SDK 的 beta 命名空間。這兩個標頭仍是有效的選擇性啟用方式，因此範例可按原樣運作，而您在自己的請求中可以省略它們。

Skills 需要程式碼執行工具，因此請使用其模型相容性清單中的模型。

在 Messages 中使用 Skills

Container 參數

Skills 是透過 Messages API 中的 container 參數來指定。每個請求最多可包含 20 個 Skills。

Anthropic 和自訂 Skills 的結構完全相同。指定必要的 type 和 skill_id，並可選擇性地包含 version 以固定至特定版本：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

下載產生的檔案

當 Skills 建立文件（Excel、PowerPoint、PDF、Word）時，會在回應中回傳 file_id 屬性。您必須使用 Files API 來下載這些檔案。

運作方式：

Skills 在程式碼執行期間建立檔案。
回應會在程式碼執行工具結果區塊中包含每個已建立檔案的 file_id（請參閱回應格式）。
使用 Files API 下載實際的檔案內容。
儲存至本機或視需要進行處理。

若要提供輸入檔案供 Skills 處理，請使用 Files API 上傳，並在您的請求中透過 container upload 區塊參照它們。

範例：建立並下載 Excel 檔案

client = anthropic.Anthropic()

# 步驟 1：使用 Skill 建立檔案
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {
            "role": "user",
            "content": "Create an Excel file with a simple budget spreadsheet",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# 步驟 2：從回應中擷取檔案 ID
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                # 每個 content 項目都是一個帶有 file_id 的 bash_code_execution_output 區塊
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# 步驟 3：使用 Files API 下載檔案
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # 步驟 4：儲存至磁碟
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

其他 Files API 操作：

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# 取得檔案中繼資料
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 列出所有檔案
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# 刪除檔案
client.beta.files.delete(file_id=file_id)

多輪對話

回應的 container 物件包含容器的 id 和 expires_at 時間戳記（有關生命週期的詳細資訊，請參閱容器重複使用）。透過指定容器 ID，在多個訊息之間重複使用相同的容器：

client = anthropic.Anthropic()

# 第一個請求會建立容器
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 使用相同容器繼續對話
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # 將助理的文字帶入後續請求；container.id 會保留執行狀態
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

長時間運行的操作

Skills 可能會執行需要多輪的操作。請處理 pause_turn 停止原因：

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 處理長時間操作的 pause_turn
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

使用多個 Skills

在單一請求中組合多個 Skills 以處理複雜的工作流程：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            },
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

管理自訂 Skills

建立 Skill

Skill 套件是一個目錄，其頂層包含一個具有 name 和 description YAML frontmatter 的 SKILL.md 檔案，以及任何支援的腳本或資源。請參閱在 API 中開始使用 Agent Skills 以撰寫一個 Skill，並參閱範例後方的需求清單以了解完整的限制條件。

上傳您的自訂 Skill 以使其在您的工作區中可用。您可以上傳 zip 封存檔或個別的檔案物件。Python SDK 也提供 files_from_dir 輔助函式，可接受目錄路徑。

檔案是透過您附加的檔名來識別（cURL 範例中的 ;filename= 後綴以及 SDK 範例中的檔名引數）。針對本逐步說明的 Skill，請使用 zip -r financial_skill.zip financial_skill/ 建立 zip 檔，並在 zip 上傳選項中將其替換為 example_skill.zip 預留位置。

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

需求：

必須在上傳根目錄（或單一封裝資料夾的頂層）包含 SKILL.md 檔案
display_name 為選用：省略時，會從 SKILL.md 的 name 衍生；明確指定的值最多可包含 255 個字元，且在工作區內不需要是唯一的
上傳總大小必須小於 30 MB（未壓縮）
YAML frontmatter 需求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不含 XML 標籤，不含保留字（「anthropic」、「claude」）
- description：最多 1024 個字元，不可為空，不含 XML 標籤

如需完整的請求/回應結構描述，請參閱 Create Skill API 參考。

列出 Skills

擷取您工作區可用的所有 Skills，包括 Anthropic 預建 Skills 和您的自訂 Skills。使用 source 參數依 Skill 類型進行篩選：

# 列出所有 Skills
ant beta:skills list

# 僅列出自訂 Skills
ant beta:skills list --source custom

如需分頁和篩選選項，請參閱 List Skills API 參考。

擷取 Skill

取得特定 Skill 的詳細資訊：

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

刪除 Skill

刪除 Skill 也會移除其所有版本。此連鎖刪除是僅限 GA 的行為，因此與本指南中的其他範例不同，這些範例直接呼叫 GA 介面，而非 beta 命名空間。

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

版本管理

Skills 支援版本管理以安全地管理更新：

Anthropic Skills：

版本使用日期格式：20251013
隨著更新發布新版本
指定確切版本以確保穩定性

自訂 Skills：

自動產生的版本 ID：skver_01AbCdEfGhIjKlMnOpQrStUv
使用 "latest" 以始終取得最新版本
更新 Skill 檔案時建立新版本

新版本是完整的快照，而非差異：每次都要上傳 Skill 的完整檔案集。您省略的檔案不會被沿用，且新版本 SKILL.md 中的 name 必須與 Skill 的現有名稱相符。以下範例會重新上傳建立 Skill 中的完整 financial_skill/ 套件。

# 建立新版本
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# 使用最新版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

如需完整詳細資訊，請參閱 Create Skill Version API 參考。

Skills 的載入方式

當您在容器中指定 Skills 時：

中繼資料探索： Claude 會在系統提示中看到每個 Skill 的中繼資料（名稱、描述）。
檔案載入： Skill 檔案會被複製到容器中的 /skills/{skill-name}/。該目錄是 Skill 的名稱（Anthropic Skill 為 pptx，自訂 Skill 為 SKILL.md 的 name），而非其 skill_01... ID。
自動使用： 當與您的請求相關時，Claude 會自動載入並使用 Skills。
組合： 多個 Skills 可組合在一起以處理複雜的工作流程。

Claude 僅在需要時才載入完整的 Skill 指令。

使用案例

Skills 適用於組織和個人工作。組織使用它們來將品牌格式套用至文件、依據公司範本組織筆記和報告，以及執行公司特定的分析程序。個人則使用它們來建立自訂文件範本、專門的資料管線，以及程式碼產生或部署慣例。

範例：財務建模

結合 Excel 和自訂 DCF 分析 Skills：

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# 建立自訂 DCF 分析 Skill

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# 搭配 Excel 使用以建立財務模型
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

限制與約束

請求限制

每個請求的最大 Skills 數量： 20
Skill 上傳大小上限： 30 MB（所有檔案合計，未壓縮）
YAML frontmatter 需求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不含 XML 標籤，不含保留字（「anthropic」、「claude」）
- description：最多 1024 個字元，不可為空，不含 XML 標籤

環境約束

Skills 在程式碼執行容器中運行，具有以下限制：

無網路存取： 無法進行外部 API 呼叫
無執行階段套件安裝： 僅可使用預先安裝的套件
隔離環境： 除非您指定現有的容器 ID，否則會建立全新的容器

如需可用套件，請參閱程式碼執行工具。

最佳實務

何時使用多個 Skills

當任務涉及多種文件類型或領域時，請組合 Skills：

適合的使用案例：

資料分析（Excel）+ 簡報建立（PowerPoint）
報告產生（Word）+ 匯出為 PDF
自訂領域邏輯 + 文件產生

避免：

包含未使用的 Skills（會影響效能）

版本管理策略

本節中的 SDK 分頁顯示要包含在 Messages 請求中的 container 值。cURL 和 CLI 分頁則顯示完整的請求。

用於生產環境： 固定特定版本，如此 Skill 更新就不會改變您已部署的行為。如果您省略 version 或將其設為 "latest"，請求會使用 Skill 的最新版本，因此工作區中任何人上傳的版本都會立即改變您生產環境代理程式所執行的內容。版本 ID 來自版本管理中的建立版本回應，或來自 List Skill Versions API。該 ID 一律為字串：在 JSON 或 YAML 中請為 epoch 時間戳記 ID 加上引號。

# 固定至特定版本以確保穩定性
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

用於開發環境： 使用 latest 以在您反覆開發時自動取得最新版本。

# 在積極開發時使用 latest
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

提示快取考量

如果您使用提示快取，變更容器中的 Skills 清單會使快取失效。Skills 會以固定順序呈現到系統提示中，因此相同的清單會產生相同的可快取前綴：

client = anthropic.Anthropic()

# Skills 會以固定且對快取友善的順序渲染至系統提示中
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 變更 Skills 清單（[xlsx] 與 [xlsx, pptx]）會改變前綴：造成快取未命中，而相同的清單則為快取命中
response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

為獲得最佳快取效能，請在各請求之間保持 Skills 清單（包括其順序）的一致性。固定自訂 Skill 版本也有幫助：使用 "latest" 時，如果發布的新版本變更了 Skill 的描述，可能會使快取的前綴失效。

錯誤處理

妥善處理與 Skill 相關的錯誤：

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # 處理技能特定的錯誤
    else:
        raise

資料保留

Agent Skills 不在 ZDR 安排的涵蓋範圍內。Skill 定義和執行資料會依據 Anthropic 的標準資料保留政策進行保留。

如需所有功能的 ZDR 適用性，請參閱 API 與資料保留。

稽核記錄

如果您的組織已啟用 Compliance API，其活動動態會記錄使用 Claude API 金鑰或從 Claude Console 進行的 Skills 和 Skill 版本的建立與刪除。在 Compliance API 關閉期間發生的操作不會被記錄，且之後無法復原，因此請在依賴此稽核軌跡之前先設定 Compliance API。

後續步驟

API 參考

包含所有端點的完整 API 參考

Skill 撰寫最佳實務

了解如何撰寫有效的 Skills，讓 Claude 能夠成功發現並使用。

程式碼執行工具

在沙箱容器中執行 Python 和 bash 程式碼，以分析資料、產生檔案並反覆改進解決方案。

Was this page helpful?

MessagesSkills

透過 API 使用 Agent Skills

了解如何透過 API 使用 Agent Skills 來擴展 Claude 的能力。

Agent Skills 透過組織化的指令、腳本和資源資料夾來擴展 Claude 的能力。本指南將向您展示如何透過 Claude API 使用預建和自訂的 Skills。

快速連結

在 API 中開始使用 Agent Skills

了解如何在 10 分鐘內使用 Agent Skills 透過 Claude API 建立文件。

Skill 撰寫最佳實務

了解如何撰寫有效的 Skills，讓 Claude 能夠成功發現並使用。

概述

使用 Skills

您可以使用來自兩種來源的 Skills：

面向	Anthropic Skills	自訂 Skills
Type 值	`anthropic`	`custom`
Skill ID	簡短名稱：`pptx`、`xlsx`、`docx`、`pdf`	自動產生：`skill_01AbCdEfGhIjKlMnOpQrStUv`
版本格式	基於日期：`20251013` 或 `latest`	版本 ID：`skver_01AbCdEfGhIjKlMnOpQrStUv` 或 `latest`
管理方式	由 Anthropic 預建並維護	透過 Skills API 上傳和管理
可用性	所有使用者皆可使用	僅限您的工作區私有

兩種 Skill 來源都會由 List Skills 端點回傳（使用 source 參數進行篩選）。整合方式和執行環境完全相同，唯一的差異在於 Skills 的來源以及管理方式。

先決條件

要使用 Skills，您需要：

來自 Claude Console 的 Claude API 金鑰
在您的請求中啟用**程式碼執行工具**

Skills 需要程式碼執行工具，因此請使用其模型相容性清單中的模型。

在 Messages 中使用 Skills

Container 參數

Skills 是透過 Messages API 中的 container 參數來指定。每個請求最多可包含 20 個 Skills。

Anthropic 和自訂 Skills 的結構完全相同。指定必要的 type 和 skill_id，並可選擇性地包含 version 以固定至特定版本：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

下載產生的檔案

當 Skills 建立文件（Excel、PowerPoint、PDF、Word）時，會在回應中回傳 file_id 屬性。您必須使用 Files API 來下載這些檔案。

運作方式：

Skills 在程式碼執行期間建立檔案。
回應會在程式碼執行工具結果區塊中包含每個已建立檔案的 file_id（請參閱回應格式）。
使用 Files API 下載實際的檔案內容。
儲存至本機或視需要進行處理。

若要提供輸入檔案供 Skills 處理，請使用 Files API 上傳，並在您的請求中透過 container upload 區塊參照它們。

範例：建立並下載 Excel 檔案

client = anthropic.Anthropic()

# 步驟 1：使用 Skill 建立檔案
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {
            "role": "user",
            "content": "Create an Excel file with a simple budget spreadsheet",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# 步驟 2：從回應中擷取檔案 ID
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                # 每個 content 項目都是一個帶有 file_id 的 bash_code_execution_output 區塊
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# 步驟 3：使用 Files API 下載檔案
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # 步驟 4：儲存至磁碟
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

其他 Files API 操作：

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# 取得檔案中繼資料
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 列出所有檔案
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

# 刪除檔案
client.beta.files.delete(file_id=file_id)

多輪對話

client = anthropic.Anthropic()

# 第一個請求會建立容器
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 使用相同容器繼續對話
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # 將助理的文字帶入後續請求；container.id 會保留執行狀態
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

長時間運行的操作

Skills 可能會執行需要多輪的操作。請處理 pause_turn 停止原因：

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 處理長時間操作的 pause_turn
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

使用多個 Skills

在單一請求中組合多個 Skills 以處理複雜的工作流程：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            },
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

管理自訂 Skills

建立 Skill

上傳您的自訂 Skill 以使其在您的工作區中可用。您可以上傳 zip 封存檔或個別的檔案物件。Python SDK 也提供 files_from_dir 輔助函式，可接受目錄路徑。

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

financial_skill/SKILL.md

---
name: financial-skill
description: Docs example skill.
---

financial_skill/analyze.py

print("financial analysis helper")

需求：

必須在上傳根目錄（或單一封裝資料夾的頂層）包含 SKILL.md 檔案
display_name 為選用：省略時，會從 SKILL.md 的 name 衍生；明確指定的值最多可包含 255 個字元，且在工作區內不需要是唯一的
上傳總大小必須小於 30 MB（未壓縮）
YAML frontmatter 需求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不含 XML 標籤，不含保留字（「anthropic」、「claude」）
- description：最多 1024 個字元，不可為空，不含 XML 標籤

如需完整的請求/回應結構描述，請參閱 Create Skill API 參考。

列出 Skills

擷取您工作區可用的所有 Skills，包括 Anthropic 預建 Skills 和您的自訂 Skills。使用 source 參數依 Skill 類型進行篩選：

# 列出所有 Skills
ant beta:skills list

# 僅列出自訂 Skills
ant beta:skills list --source custom

如需分頁和篩選選項，請參閱 List Skills API 參考。

擷取 Skill

取得特定 Skill 的詳細資訊：

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

刪除 Skill

刪除 Skill 也會移除其所有版本。此連鎖刪除是僅限 GA 的行為，因此與本指南中的其他範例不同，這些範例直接呼叫 GA 介面，而非 beta 命名空間。

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

版本管理

Skills 支援版本管理以安全地管理更新：

Anthropic Skills：

版本使用日期格式：20251013
隨著更新發布新版本
指定確切版本以確保穩定性

自訂 Skills：

自動產生的版本 ID：skver_01AbCdEfGhIjKlMnOpQrStUv
使用 "latest" 以始終取得最新版本
更新 Skill 檔案時建立新版本

# 建立新版本
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# 使用最新版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: latest
messages:
  - role: user
    content: Use latest Skill version
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

如需完整詳細資訊，請參閱 Create Skill Version API 參考。

Skills 的載入方式

當您在容器中指定 Skills 時：

中繼資料探索： Claude 會在系統提示中看到每個 Skill 的中繼資料（名稱、描述）。
檔案載入： Skill 檔案會被複製到容器中的 /skills/{skill-name}/。該目錄是 Skill 的名稱（Anthropic Skill 為 pptx，自訂 Skill 為 SKILL.md 的 name），而非其 skill_01... ID。
自動使用： 當與您的請求相關時，Claude 會自動載入並使用 Skills。
組合： 多個 Skills 可組合在一起以處理複雜的工作流程。

Claude 僅在需要時才載入完整的 Skill 指令。

使用案例

範例：財務建模

結合 Excel 和自訂 DCF 分析 Skills：

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# 建立自訂 DCF 分析 Skill

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# 搭配 Excel 使用以建立財務模型
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

限制與約束

請求限制

每個請求的最大 Skills 數量： 20
Skill 上傳大小上限： 30 MB（所有檔案合計，未壓縮）
YAML frontmatter 需求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不含 XML 標籤，不含保留字（「anthropic」、「claude」）
- description：最多 1024 個字元，不可為空，不含 XML 標籤

環境約束

Skills 在程式碼執行容器中運行，具有以下限制：

無網路存取： 無法進行外部 API 呼叫
無執行階段套件安裝： 僅可使用預先安裝的套件
隔離環境： 除非您指定現有的容器 ID，否則會建立全新的容器

如需可用套件，請參閱程式碼執行工具。

最佳實務

何時使用多個 Skills

當任務涉及多種文件類型或領域時，請組合 Skills：

適合的使用案例：

資料分析（Excel）+ 簡報建立（PowerPoint）
報告產生（Word）+ 匯出為 PDF
自訂領域邏輯 + 文件產生

避免：

包含未使用的 Skills（會影響效能）

版本管理策略

本節中的 SDK 分頁顯示要包含在 Messages 請求中的 container 值。cURL 和 CLI 分頁則顯示完整的請求。

# 固定至特定版本以確保穩定性
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",
        }
    ]
}

用於開發環境： 使用 latest 以在您反覆開發時自動取得最新版本。

# 在積極開發時使用 latest
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

提示快取考量

如果您使用提示快取，變更容器中的 Skills 清單會使快取失效。Skills 會以固定順序呈現到系統提示中，因此相同的清單會產生相同的可快取前綴：

client = anthropic.Anthropic()

# Skills 會以固定且對快取友善的順序渲染至系統提示中
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 變更 Skills 清單（[xlsx] 與 [xlsx, pptx]）會改變前綴：造成快取未命中，而相同的清單則為快取命中
response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

錯誤處理

妥善處理與 Skill 相關的錯誤：

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # 處理技能特定的錯誤
    else:
        raise

資料保留

Agent Skills 不在 ZDR 安排的涵蓋範圍內。Skill 定義和執行資料會依據 Anthropic 的標準資料保留政策進行保留。

如需所有功能的 ZDR 適用性，請參閱 API 與資料保留。

稽核記錄

後續步驟

API 參考

包含所有端點的完整 API 參考

Skill 撰寫最佳實務

了解如何撰寫有效的 Skills，讓 Claude 能夠成功發現並使用。

程式碼執行工具

在沙箱容器中執行 Python 和 bash 程式碼，以分析資料、產生檔案並反覆改進解決方案。

Was this page helpful?

快速連結

概述

使用 Skills

先決條件

在 Messages 中使用 Skills

Container 參數

下載產生的檔案

多輪對話

長時間運行的操作

使用多個 Skills

管理自訂 Skills

建立 Skill

列出 Skills

擷取 Skill

刪除 Skill

版本管理

Skills 的載入方式

使用案例

範例：財務建模

限制與約束

請求限制

環境約束

最佳實務

何時使用多個 Skills

版本管理策略

提示快取考量

錯誤處理

資料保留

稽核記錄

後續步驟

快速連結

概述

使用 Skills

先決條件

在 Messages 中使用 Skills

Container 參數

下載產生的檔案

多輪對話

長時間運行的操作

使用多個 Skills

管理自訂 Skills

建立 Skill

列出 Skills

擷取 Skill

刪除 Skill

版本管理

Skills 的載入方式

使用案例

範例：財務建模

限制與約束

請求限制

環境約束

最佳實務

何時使用多個 Skills

版本管理策略

提示快取考量

錯誤處理

資料保留

稽核記錄

後續步驟

快速連結

概述

使用 Skills

先決條件

在 Messages 中使用 Skills

Container 參數

下載產生的檔案

多輪對話

長時間運行的操作

使用多個 Skills

管理自訂 Skills

建立 Skill

列出 Skills

擷取 Skill

刪除 Skill

版本管理

Skills 的載入方式

使用案例

範例：財務建模

限制與約束

請求限制

環境約束

最佳實務

何時使用多個 Skills

版本管理策略

提示快取考量

錯誤處理

資料保留

稽核記錄

後續步驟

快速連結

概述

使用 Skills

先決條件

在 Messages 中使用 Skills

Container 參數

下載產生的檔案

多輪對話

長時間運行的操作

使用多個 Skills

管理自訂 Skills

建立 Skill

列出 Skills

擷取 Skill

刪除 Skill

版本管理

Skills 的載入方式

使用案例

範例：財務建模

限制與約束

請求限制

環境約束

最佳實務

何時使用多個 Skills

版本管理策略

提示快取考量

錯誤處理

資料保留

稽核記錄

後續步驟