API 中的技能

建構技能

透過 API 使用 Agent Skills

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

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

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

Skill Management API Reference - Skills 的 CRUD 操作
Skill Versions API Reference - 版本管理

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

快速連結

開始使用 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`
管理	由 Anthropic 預先建立和維護	透過 Skills API 上傳和管理
可用性	對所有使用者可用	私有於您的工作區

兩個 Skill 來源都由 List Skills 端點返回（使用 source 參數進行篩選）。整合形式和執行環境相同。唯一的差異是 Skills 的來源和管理方式。

先決條件

若要使用 Skills，您需要：

Claude API 金鑰，來自 Console
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-7",
    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 文件

其他 Files API 操作：

client = anthropic.Anthropic()
file_id = "file_abc123"
# 取得文件元數據
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"])

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

多輪對話

通過指定容器 ID 在多個消息中重複使用同一容器：

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

長時間運行的操作

技能可能執行需要多個回合的操作。處理 pause_turn 停止原因：

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

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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-7",
        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 暫停了長時間運行的技能操作。您可以在後續請求中按原樣提供回應，讓 Claude 繼續其回合，或者修改內容以中斷對話並提供額外的指導。

使用多個技能

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

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

要求：

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

如需完整的請求/回應架構，請參閱建立技能 API 參考。

列出技能

檢索您的工作區中可用的所有技能，包括 Anthropic 預先建立的技能和您的自訂技能。使用 source 參數按技能類型進行篩選：

# 列出所有技能
ant beta:skills list

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

如需分頁和篩選選項，請參閱列出技能 API 參考。

檢索技能

取得特定技能的詳細資訊：

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

刪除技能

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

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

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

嘗試刪除具有現有版本的技能會返回 400 錯誤。

版本控制

技能支持版本控制以安全地管理更新：

Anthropic 管理的技能：

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

自訂技能：

自動生成的紀元時間戳：1759178010641129
使用 "latest" 以始終獲取最新版本
更新技能文件時建立新版本

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

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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-7
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

請參閱建立技能版本 API 參考以取得完整詳細資訊。

技能如何被載入

當您在容器中指定技能時：

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

漸進式揭露架構確保了高效的上下文使用：Claude 只在需要時載入完整的技能說明。

使用案例

組織技能

品牌與通訊

將公司特定的格式（顏色、字體、佈局）應用於文件
按照組織範本生成通訊
確保所有輸出中的品牌指南一致

專案管理

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

業務營運

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

個人技能

內容建立

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

資料分析

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

開發與自動化

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

範例：財務建模

結合 Excel 和自訂 DCF 分析 Skills：

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

限制和約束

請求限制

每個請求的最大 Skills 數量： 8
最大 Skill 上傳大小： 30 MB（所有檔案合計）
YAML 前置資料要求：
- 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",  # 特定版本
        }
    ]
}

用於開發環境：

# 使用最新版本進行主動開發
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # 始終取得最新版本
        }
    ]
}

提示快取考量

使用提示快取時，請注意在容器中變更 Skills 清單會破壞快取：

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

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

錯誤處理

優雅地處理技能相關的錯誤：

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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}")
        # Handle skill-specific errors
    else:
        raise

資料保留

Agent Skills 不受 ZDR 安排的涵蓋。技能定義和執行資料根據 Anthropic 的標準資料保留政策進行保留。

如需了解所有功能的 ZDR 資格，請參閱 API 和資料保留。

後續步驟

API 參考

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

編寫指南

編寫有效技能的最佳實踐

程式碼執行工具

了解程式碼執行環境

Was this page helpful?

建構技能

透過 API 使用 Agent Skills

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

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

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

Skill Management API Reference - Skills 的 CRUD 操作
Skill Versions API Reference - 版本管理

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

快速連結

開始使用 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，您需要：

Claude API 金鑰，來自 Console
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-7",
    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 文件

其他 Files API 操作：

client = anthropic.Anthropic()
file_id = "file_abc123"
# 取得文件元數據
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"])

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

多輪對話

通過指定容器 ID 在多個消息中重複使用同一容器：

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

長時間運行的操作

技能可能執行需要多個回合的操作。處理 pause_turn 停止原因：

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

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

要求：

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

如需完整的請求/回應架構，請參閱建立技能 API 參考。

列出技能

檢索您的工作區中可用的所有技能，包括 Anthropic 預先建立的技能和您的自訂技能。使用 source 參數按技能類型進行篩選：

# 列出所有技能
ant beta:skills list

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

如需分頁和篩選選項，請參閱列出技能 API 參考。

檢索技能

取得特定技能的詳細資訊：

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

刪除技能

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

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

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

嘗試刪除具有現有版本的技能會返回 400 錯誤。

版本控制

技能支持版本控制以安全地管理更新：

Anthropic 管理的技能：

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

自訂技能：

自動生成的紀元時間戳：1759178010641129
使用 "latest" 以始終獲取最新版本
更新技能文件時建立新版本

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

# 使用特定版本
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-7
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-7
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

請參閱建立技能版本 API 參考以取得完整詳細資訊。

技能如何被載入

當您在容器中指定技能時：

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

漸進式揭露架構確保了高效的上下文使用：Claude 只在需要時載入完整的技能說明。

使用案例

組織技能

品牌與通訊

將公司特定的格式（顏色、字體、佈局）應用於文件
按照組織範本生成通訊
確保所有輸出中的品牌指南一致

專案管理

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

業務營運

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

個人技能

內容建立

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

資料分析

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

開發與自動化

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

範例：財務建模

結合 Excel 和自訂 DCF 分析 Skills：

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

限制和約束

請求限制

每個請求的最大 Skills 數量： 8
最大 Skill 上傳大小： 30 MB（所有檔案合計）
YAML 前置資料要求：
- 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",  # 特定版本
        }
    ]
}

用於開發環境：

# 使用最新版本進行主動開發
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # 始終取得最新版本
        }
    ]
}

提示快取考量

使用提示快取時，請注意在容器中變更 Skills 清單會破壞快取：

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

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

錯誤處理

優雅地處理技能相關的錯誤：

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        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}")
        # Handle skill-specific errors
    else:
        raise

資料保留

Agent Skills 不受 ZDR 安排的涵蓋。技能定義和執行資料根據 Anthropic 的標準資料保留政策進行保留。

如需了解所有功能的 ZDR 資格，請參閱 API 和資料保留。

後續步驟

API 參考

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

編寫指南

編寫有效技能的最佳實踐

程式碼執行工具

了解程式碼執行環境

Was this page helpful?