透過 API 使用 Agent Skills

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 參數中指定 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 取得的 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 以固定至特定版本：

下載產生的檔案

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

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

需求：

必須在頂層包含一個 SKILL.md 檔案
所有檔案必須在其路徑中指定一個共同的根目錄
總上傳大小必須小於 30 MB
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 檔案時建立新版本

請參閱 Create Skill Version API 參考以取得完整詳細資訊。

Skills 的載入方式

當您在容器中指定 Skills 時：

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

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

使用案例

組織型 Skills

品牌與溝通

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

專案管理

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

業務營運

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

個人型 Skills

內容創作

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

資料分析

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

開發與自動化

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

範例：財務建模

結合 Excel 和自訂 DCF 分析 Skills：

限制與約束

請求限制

每個請求的最大 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
        }
    ]
}

提示快取注意事項

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

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

錯誤處理

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

資料保留

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

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

後續步驟

API 參考

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

撰寫指南

撰寫有效 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": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

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":
                # 具體型別的清單：List[BashCodeExecutionOutputBlock]
                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}")

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

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

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

# 第一個請求會建立容器
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 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-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"}],
)

messages = [{"role": "user", "content": "Process this large 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 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-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"}],
    )

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"}],
)

# 選項 1：上傳個別檔案（每個檔案使用一個 --file 旗標）
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# 選項 2：上傳 zip 壓縮檔
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

# 步驟 1：刪除所有版本
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output \
  | while read -r VERSION; do
      ant beta:skills:versions delete \
        --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
        --version "$VERSION" >/dev/null
    done

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

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

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta 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 \
  --beta 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

# 建立自訂 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"),
)

# 搭配 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 with the attached financials",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

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

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

快速連結

概述

使用 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

版本管理策略

提示快取注意事項

錯誤處理

資料保留

後續步驟