Claude Platform Docs
MessagesSkills

透過 API 使用 Agent Skills

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

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

在 API 中開始使用 Agent Skills

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

Skill 撰寫最佳實務

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

概覽

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

使用 Skills

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

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

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

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

先決條件

要使用 Skills，您需要：

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

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

在 Messages 中使用 Skills

Container 參數

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 來下載這些檔案。

運作方式：

  1. Skills 在程式碼執行期間建立檔案。
  2. 回應會在程式碼執行工具結果區塊中，為每個建立的檔案包含一個 file_id（請參閱回應格式）。
  3. 使用 Files API 下載實際的檔案內容。
  4. 儲存至本機或依需求處理。

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

範例：建立並下載 Excel 檔案

client = anthropic.Anthropic()

# 步驟 1：使用 Skill 建立檔案
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.files.retrieve_metadata(file_id=file_id)
    file_content = client.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.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

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

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

多輪對話

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

client = anthropic.Anthropic()

# 第一個請求會建立容器
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 skills create --file financial_skill.zip
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 標籤

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

列出 Skills

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

# 列出所有 Skills
ant skills list

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

有關分頁與篩選選項，請參閱列出 Skills API 參考。

擷取 Skill

取得特定 Skill 的詳細資訊：

ant skills retrieve --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

刪除 Skill

刪除 Skill 也會移除其所有版本。

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_ID=$(ant skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform id \
  --raw-output)

# 使用特定版本
ant messages create <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_ID"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# 使用最新版本
ant messages create <<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

如需完整詳細資訊，請參閱建立 Skill 版本 API 參考。

Skills 的載入方式

當您在容器中指定 Skills 時：

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

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

使用案例

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

範例：財務建模

結合 Excel 與自訂 DCF 分析 Skills：

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# 建立自訂 DCF 分析 Skill

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

# 搭配 Excel 使用以建立財務模型
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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 來自版本管理中建立版本的回應，或來自列出 Skill 版本 API。該 ID 始終是字串，因此即使它看起來像數字，也請在 JSON 或 YAML 中加上引號。

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

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

# 進行中的開發請使用 latest
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

提示快取注意事項

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

client = anthropic.Anthropic()

# Skills 會以固定且有利於快取的順序呈現至系統提示中
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    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.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        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}")
        # 處理 skill 特定的錯誤
    else:
        raise

從 skills-2025-10-02 遷移

Skills API 已結束 beta 階段，不再需要 beta 標頭。從 skills-2025-10-02 遷移是選擇性的：仍然傳送該標頭的請求會繼續運作，並繼續傳回 beta 回應結構，因此現有的整合在您變更之前都會持續運作。移除該標頭會將這些請求切換為本頁所記載的結構：

使用 skills-2025-10-02不使用該標頭
Skill 標籤display_title（最多 64 個字元，每個工作區內唯一）display_name（最多 255 個字元，不需唯一）；省略時從 SKILL.md 的 name 衍生
最新版本指標latest_version，一個 epoch 微秒字串，例如 "1759178010641129"latest_version_id，一個版本 ID，例如 "skver_01AbCdEfGhIjKlMnOpQrStUv"；GET /v1/skills/{skill_id}/versions/latest 可在一次呼叫中解析它
URL 中的版本識別碼Epoch 微秒字串版本 ID（skver_...）。在 beta 期間以 skill_version_ 前綴擷取的 ID 可作為輸入被接受。
版本物件包含 directory（始終等於 Skill 的 name）無 directory 欄位
source字串，"custom" 或 "anthropic"物件，例如 {"type": "custom"}；範例目錄的值為 "anthropic_example"
列表回應{ data, has_more, next_page }{ data, next_page }；limit 從 1 到 1,000（預設 20）
版本列表順序最舊的在前最新的在前，預設 limit 為 20。一種結構的分頁游標在另一種結構上無效。
刪除 Skill只要存在任何版本就傳回 400 錯誤刪除 Skill 及其所有版本
刪除 Skill 的唯一版本允許，留下一個沒有版本的 Skill傳回 400 錯誤；請先上傳替代版本，或刪除該 Skill
上傳配置檔案必須位於名稱與 Skill name 相符的頂層目錄內SKILL.md 可位於上傳的根目錄；無論哪種方式，儲存的路徑都相同
回應類型CreateSkillResponse、GetSkillResponse，以及每個操作一種類型Skill、SkillVersion、DeletedSkill、DeletedSkillVersion

遷移步驟：

  1. 移除 beta 標頭。 從您的請求中移除 anthropic-beta: skills-2025-10-02。在 SDK 中，呼叫 client.skills 而非 client.beta.skills；繼續使用 client.beta.skills 僅在不再傳送該標頭的 SDK 版本上有效。較早的版本即使沒有 betas 引數，也會從 client.beta.skills 傳送該標頭。
  2. 重新命名欄位：在您的程式碼中將 display_title 改為 display_name、latest_version 改為 latest_version_id，並讀取 source.type 而非將 source 與字串比較。
  3. 使用版本 ID。 凡是您儲存 epoch 微秒版本之處，請改為儲存版本的 id，或使用 latest。Messages 請求中的 Skill 參照接受版本 ID、latest，或（對於 Anthropic Skills）目錄版本。
  4. 檢視刪除呼叫。 DELETE /v1/skills/{skill_id} 現在會連同 Skill 一起移除每個版本。如果您先前依賴 beta 的拒絕行為作為保護措施，請自行加入檢查。

在 beta 期間所有版本都已被刪除的 Skill 沒有可傳回的目前版本：GET /v1/skills/{skill_id} 會傳回 400 錯誤，且該 Skill 會從列表回應中省略，直到您為其上傳一個版本為止。您仍然可以刪除它。

SDK beta 命名空間

從 Python SDK 1.2.0、TypeScript SDK 0.122.0、Go SDK 1.68.0、Java SDK 2.59.0、Ruby SDK 1.67.0 與 C# SDK 12.44.0 開始，client.beta.skills 不再傳送 skills-2025-10-02，並傳回與 client.skills 相同的結構，但類型名稱帶有 Beta 前綴（BetaSkill、BetaSkillVersion、BetaDeletedSkill、BetaDeletedSkillVersion）。它接受 betas 引數，用於仍處於 beta 階段的 Skills 功能。在 beta Messages 類型中，容器 Skill 參照類型已從 BetaSkill 重新命名為 BetaContainerSkill（欄位相同：type、skill_id、version）；BetaSkill 現在用於命名 Skill 資源，與非 beta 類型中的 Skill 與 ContainerSkill 相對應。較早的 SDK 版本是依 beta 結構定型的；如果您依賴這些類型，請在遷移之前停留在較早的版本。

資料保留

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

有關所有功能的 ZDR 資格，請參閱 API 與資料保留。

稽核記錄

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

後續步驟

API 參考

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

Skill 撰寫最佳實務

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

程式碼執行工具

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

Was this page helpful?