訊息技能

透過 API 使用 Agent Skills

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

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

如需完整的 API 參考，包括請求/回應結構和所有參數，請參閱：

Skill 管理 API 參考 - Skills 的 CRUD 操作
Skill 版本 API 參考 - 版本管理

此功能不符合零資料保留（Zero Data Retention，ZDR）的資格。資料將依據該功能的標準保留政策進行保留。

快速連結

開始使用 Agent Skills

建立您的第一個 Skill

建立自訂 Skills

撰寫 Skills 的最佳實踐

概觀

如需深入了解 Agent Skills 的架構和實際應用，請閱讀工程部落格文章：Equipping agents for the real world with Agent Skills。

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

使用 Skills

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

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

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

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

先決條件

要使用 Skills，您需要：

來自 Console 的 Claude API 金鑰
Beta 標頭：
- code-execution-2025-08-25 - 啟用程式碼執行（Skills 必需）
- skills-2025-10-02 - 啟用 Skills API
- files-api-2025-04-14 - 用於上傳/下載檔案至/自容器
在您的請求中啟用**程式碼執行工具**

在 Messages 中使用 Skills

Container 參數

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

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 下載實際的檔案內容。
儲存至本機或視需要進行處理。

範例：建立並下載 Excel 檔案

client = anthropic.Anthropic()

# 步驟 1：使用 Skill 建立檔案
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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":
                # 每個內容項目都是帶有 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)

如需 Files API 的完整詳細資訊，請參閱 Files API 文件。

多輪對話

透過指定容器 ID，在多個訊息之間重複使用同一個容器：

client = anthropic.Anthropic()

# 第一個請求會建立容器
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-4-8",
    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-4-8",
    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-4-8",
        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"}],
    )

回應可能包含 pause_turn 停止原因，這表示 API 暫停了長時間執行的 Skill 操作。您可以在後續請求中原封不動地提供該回應，讓 Claude 繼續其回合；或者如果您希望中斷對話並提供額外指引，也可以修改內容。

使用多個 Skills

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 套件（bundle）是一個目錄，其頂層包含一個帶有 name 和 description YAML frontmatter 的 SKILL.md 檔案，以及任何支援的腳本或資源。請參閱在 API 中開始使用 Agent Skills 來撰寫一個 Skill，並參閱範例後面的需求清單以了解完整的限制。

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

檔案是透過您附加的檔案名稱來識別的。逐檔上傳時，其路徑必須保持一個共同的頂層目錄（cURL 範例中的 ;filename= 後綴以及 SDK 範例中的檔案名稱引數），而 zip 壓縮檔必須將 skill 目錄作為其唯一的頂層項目。

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# 逐檔上傳需要帶有路徑的檔案名稱，而 CLI
# 目前無法設定。請改為上傳 zip 壓縮檔。

需求：

頂層必須包含一個 SKILL.md 檔案
所有檔案的路徑都必須指定一個共同的根目錄
頂層目錄名稱必須與 SKILL.md frontmatter 中的 name 相符（不區分大小寫和底線：Financial_Skill 與 financial-skill 相符）
display_title 為可選：省略時，會從 SKILL.md 的 name 衍生；明確指定的值在您工作區的自訂 skills 中必須是唯一的
總上傳大小必須小於 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，您必須先刪除其所有版本：

# 步驟 1：列出所有版本，然後逐一刪除
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# 對清單回傳的每個版本 id 重複此操作
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# 步驟 2：刪除 Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

嘗試刪除仍有現存版本的 Skill 會回傳 400 錯誤。

版本管理

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

Anthropic Skills：

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

自訂 Skills：

自動產生的 epoch 時間戳記：1759178010641129
使用 "latest" 以始終取得最新版本
更新 Skill 檔案時建立新版本

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

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-4-8
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-4-8
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/{directory}/。
自動使用： 當與您的請求相關時，Claude 會自動載入並使用 Skills。
組合： 多個 Skills 可以組合在一起以處理複雜的工作流程。

漸進式揭露（progressive disclosure）架構確保了高效的上下文使用：Claude 只在需要時才載入完整的 Skill 指令。

使用案例

組織 Skills

品牌與溝通

將公司特定的格式（顏色、字型、版面配置）套用至文件
依照組織範本產生溝通內容
確保所有輸出都符合一致的品牌準則

專案管理

使用公司特定格式（OKR、決策日誌）來組織筆記
依照團隊慣例產生任務
建立標準化的會議摘要和狀態更新

業務營運

建立公司標準的報告、提案和分析
執行公司特定的分析程序
依照組織範本產生財務模型

個人 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-4-8",
    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 數量： 8
Skill 上傳大小上限： 30 MB（所有檔案合計）
YAML frontmatter 需求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不可包含 XML 標籤，不可使用保留字（「anthropic」、「claude」）
- description：最多 1024 個字元，不可為空，不可包含 XML 標籤

環境約束

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

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

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

最佳實踐

何時使用多個 Skills

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

良好的使用案例：

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

避免：

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

版本管理策略

用於正式環境：

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

用於開發環境：

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

提示快取注意事項

使用提示快取（prompt caching）時，請注意變更容器中的 Skills 清單會使快取失效：

client = anthropic.Anthropic()

# 第一個請求會建立快取
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 會使快取失效
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

為了獲得最佳的快取效能，請在各個請求之間保持 Skills 清單的一致性。

錯誤處理

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

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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?

訊息技能

透過 API 使用 Agent Skills

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

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

如需完整的 API 參考，包括請求/回應結構和所有參數，請參閱：

Skill 管理 API 參考 - Skills 的 CRUD 操作
Skill 版本 API 參考 - 版本管理

此功能不符合零資料保留（Zero Data Retention，ZDR）的資格。資料將依據該功能的標準保留政策進行保留。

快速連結

開始使用 Agent Skills

建立您的第一個 Skill

建立自訂 Skills

撰寫 Skills 的最佳實踐

概觀

如需深入了解 Agent Skills 的架構和實際應用，請閱讀工程部落格文章：Equipping agents for the real world with Agent Skills。

使用 Skills

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

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

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

先決條件

要使用 Skills，您需要：

來自 Console 的 Claude API 金鑰
Beta 標頭：
- code-execution-2025-08-25 - 啟用程式碼執行（Skills 必需）
- skills-2025-10-02 - 啟用 Skills API
- files-api-2025-04-14 - 用於上傳/下載檔案至/自容器
在您的請求中啟用**程式碼執行工具**

在 Messages 中使用 Skills

Container 參數

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

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 下載實際的檔案內容。
儲存至本機或視需要進行處理。

範例：建立並下載 Excel 檔案

client = anthropic.Anthropic()

# 步驟 1：使用 Skill 建立檔案
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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":
                # 每個內容項目都是帶有 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)

如需 Files API 的完整詳細資訊，請參閱 Files API 文件。

多輪對話

透過指定容器 ID，在多個訊息之間重複使用同一個容器：

client = anthropic.Anthropic()

# 第一個請求會建立容器
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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-4-8",
    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-4-8",
    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-4-8",
        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-4-8",
    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

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

# 逐檔上傳需要帶有路徑的檔案名稱，而 CLI
# 目前無法設定。請改為上傳 zip 壓縮檔。

需求：

頂層必須包含一個 SKILL.md 檔案
所有檔案的路徑都必須指定一個共同的根目錄
頂層目錄名稱必須與 SKILL.md frontmatter 中的 name 相符（不區分大小寫和底線：Financial_Skill 與 financial-skill 相符）
display_title 為可選：省略時，會從 SKILL.md 的 name 衍生；明確指定的值在您工作區的自訂 skills 中必須是唯一的
總上傳大小必須小於 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，您必須先刪除其所有版本：

# 步驟 1：列出所有版本，然後逐一刪除
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# 對清單回傳的每個版本 id 重複此操作
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 1759178010641129 >/dev/null

# 步驟 2：刪除 Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

嘗試刪除仍有現存版本的 Skill 會回傳 400 錯誤。

版本管理

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

Anthropic Skills：

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

自訂 Skills：

自動產生的 epoch 時間戳記：1759178010641129
使用 "latest" 以始終取得最新版本
更新 Skill 檔案時建立新版本

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

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-4-8
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-4-8
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/{directory}/。
自動使用： 當與您的請求相關時，Claude 會自動載入並使用 Skills。
組合： 多個 Skills 可以組合在一起以處理複雜的工作流程。

漸進式揭露（progressive disclosure）架構確保了高效的上下文使用：Claude 只在需要時才載入完整的 Skill 指令。

使用案例

組織 Skills

品牌與溝通

將公司特定的格式（顏色、字型、版面配置）套用至文件
依照組織範本產生溝通內容
確保所有輸出都符合一致的品牌準則

專案管理

使用公司特定格式（OKR、決策日誌）來組織筆記
依照團隊慣例產生任務
建立標準化的會議摘要和狀態更新

業務營運

建立公司標準的報告、提案和分析
執行公司特定的分析程序
依照組織範本產生財務模型

個人 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-4-8",
    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 數量： 8
Skill 上傳大小上限： 30 MB（所有檔案合計）
YAML frontmatter 需求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不可包含 XML 標籤，不可使用保留字（「anthropic」、「claude」）
- description：最多 1024 個字元，不可為空，不可包含 XML 標籤

環境約束

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

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

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

最佳實踐

何時使用多個 Skills

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

良好的使用案例：

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

避免：

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

版本管理策略

用於正式環境：

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

用於開發環境：

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

提示快取注意事項

使用提示快取（prompt caching）時，請注意變更容器中的 Skills 清單會使快取失效：

client = anthropic.Anthropic()

# 第一個請求會建立快取
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 會使快取失效
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

為了獲得最佳的快取效能，請在各個請求之間保持 Skills 清單的一致性。

錯誤處理

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

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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

範例：財務建模

限制與約束

請求限制

環境約束

最佳實踐

何時使用多個 Skills

版本管理策略

提示快取注意事項

錯誤處理

資料保留

後續步驟

快速連結

概觀

使用 Skills

先決條件

在 Messages 中使用 Skills

Container 參數

下載產生的檔案

多輪對話

長時間執行的操作

使用多個 Skills

管理自訂 Skills

建立 Skill

列出 Skills

擷取 Skill

刪除 Skill

版本管理

Skills 的載入方式

使用案例

組織 Skills

個人 Skills

範例：財務建模

限制與約束

請求限制

環境約束

最佳實踐

何時使用多個 Skills

版本管理策略

提示快取注意事項

錯誤處理

資料保留

後續步驟

快速連結

概觀

使用 Skills

先決條件

在 Messages 中使用 Skills

Container 參數

下載產生的檔案

多輪對話

長時間執行的操作

使用多個 Skills

管理自訂 Skills

建立 Skill

列出 Skills

擷取 Skill

刪除 Skill

版本管理

Skills 的載入方式

使用案例

組織 Skills

個人 Skills

範例：財務建模

限制與約束

請求限制

環境約束

最佳實踐

何時使用多個 Skills

版本管理策略

提示快取注意事項

錯誤處理

資料保留

後續步驟

快速連結

概觀

使用 Skills

先決條件

在 Messages 中使用 Skills

Container 參數

下載產生的檔案

多輪對話

長時間執行的操作

使用多個 Skills

管理自訂 Skills

建立 Skill

列出 Skills

擷取 Skill

刪除 Skill

版本管理

Skills 的載入方式

使用案例

組織 Skills

個人 Skills

範例：財務建模

限制與約束

請求限制

環境約束

最佳實踐

何時使用多個 Skills

版本管理策略

提示快取注意事項

錯誤處理

資料保留

後續步驟