透過 API 使用 Agent Skills

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

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

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

快速連結

開始使用 Agent Skills

建立您的第一個 Skill

建立自訂 Skills

撰寫 Skills 的最佳實踐

概述

如需深入了解 Agent Skills 的架構和實際應用，請閱讀我們的工程部落格：為真實世界的代理配備 Agent Skills。

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`	Epoch 時間戳：`1759178010641129` 或 `latest`
管理方式

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

先決條件

要使用 Skills，您需要：

從 Console 取得 Anthropic 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 以鎖定特定版本：

下載生成的檔案

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

運作方式：

Skills 在程式碼執行期間建立檔案
回應中包含每個建立檔案的 file_id
使用 Files API 下載實際的檔案內容
儲存到本地或根據需要進行處理

範例：建立並下載 Excel 檔案

其他 Files API 操作：

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

多輪對話

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

長時間執行的操作

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

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

使用多個 Skills

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

管理自訂 Skills

建立 Skill

上傳您的自訂 Skill 以使其在您的工作區中可用。您可以使用目錄路徑或個別檔案物件進行上傳。

要求：

必須在頂層包含一個 SKILL.md 檔案
所有檔案必須在其路徑中指定一個共同的根目錄
總上傳大小必須低於 8MB
YAML frontmatter 要求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不可包含 XML 標籤，不可使用保留字（"anthropic"、"claude"）
- description：最多 1024 個字元，不可為空，不可包含 XML 標籤

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

列出 Skills

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

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

擷取 Skill

取得特定 Skill 的詳細資訊：

刪除 Skill

要刪除 Skill，您必須先刪除其所有版本：

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

版本管理

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

Anthropic 管理的 Skills：

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

自訂 Skills：

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

請參閱建立 Skill 版本 API 參考以獲取完整詳情。

Skills 的載入方式

當您在容器中指定 Skills 時：

中繼資料探索：Claude 在系統提示中看到每個 Skill 的中繼資料（名稱、描述）
檔案載入：Skill 檔案被複製到容器中的 /skills/{directory}/
自動使用：當與您的請求相關時，Claude 會自動載入並使用 Skills
組合：多個 Skills 可以組合在一起處理複雜的工作流程

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

使用案例

組織 Skills

品牌與溝通

將公司特定的格式（顏色、字型、版面配置）套用到文件
按照組織範本生成溝通內容
確保所有輸出遵循一致的品牌指南

專案管理

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

業務營運

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

個人 Skills

內容創作

自訂文件範本
專門的格式和樣式
特定領域的內容生成

資料分析

自訂資料處理管線
專門的視覺化範本
特定產業的分析方法

開發與自動化

程式碼生成範本
測試框架
部署工作流程

範例：財務建模

結合 Excel 和自訂 DCF 分析 Skills：

限制與約束

請求限制

每個請求的最大 Skills 數量：8
最大 Skill 上傳大小：8MB（所有檔案合計）
YAML frontmatter 要求：
- name：最多 64 個字元，僅限小寫字母/數字/連字號，不可包含 XML 標籤，不可使用保留字
- description：最多 1024 個字元，不可為空，不可包含 XML 標籤

環境約束

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

無網路存取 — 無法進行外部 API 呼叫
無法在執行時安裝套件 — 僅可使用預先安裝的套件
隔離環境 — 每個請求都會取得一個全新的容器

請參閱程式碼執行工具文件以了解可用的套件。

最佳實踐

何時使用多個 Skills

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

適合的使用案例：

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

避免：

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

版本管理策略

用於生產環境：

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

用於開發環境：

# 在積極開發時使用 latest
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # 始終取得最新版本
    }]
}

提示快取注意事項

使用提示快取時，請注意更改容器中的 Skills 列表將會使快取失效：

為了獲得最佳快取效能，請在各請求之間保持 Skills 列表一致。

錯誤處理

優雅地處理與 Skill 相關的錯誤：

後續步驟

API 參考

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"
    }]
)

import anthropic

client = anthropic.Anthropic()

# 步驟 1：使用 Skill 建立檔案
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        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,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

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

# 取得檔案中繼資料
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# 列出所有檔案
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# 刪除檔案
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

# 第一個請求建立容器
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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 this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# 使用相同容器繼續對話
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

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

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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 i 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-6",
        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"}]
    )

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"
    }]
)

import anthropic

client = anthropic.Anthropic()

# 選項 1：使用 files_from_dir 輔助函式（僅限 Python，推薦）
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"]
)

# 選項 2：使用 zip 檔案
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# 選項 3：使用檔案元組（filename, file_content, mime_type）
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

# 列出所有 Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# 僅列出自訂 Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

# 步驟 1：刪除所有版本
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# 步驟 2：刪除 Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

# 建立新版本
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# 使用特定版本
response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# 使用最新版本
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# 建立自訂 DCF 分析 Skill
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"]
)

# 與 Excel 搭配使用以建立財務模型
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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 with the attached financials"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# 第一個請求建立快取
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    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-6",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"}  # 快取未命中
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

try:
    response = client.beta.messages.create(
        model="claude-opus-4-6",
        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}")
        # 處理 skill 特定的錯誤
    else:
        raise