如需完整的 API 參考資料,包括請求/回應架構和所有參數,請參閱:
- Skill 管理 API 參考 - Skills 的 CRUD 操作
- Skill 版本 API 參考 - 版本管理
快速連結
概述
如需深入了解 Agent Skills 的架構和實際應用,請閱讀我們的工程部落格:使用 Agent 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 | 紀元時間戳:1759178010641129 或 latest |
管理 | 由 Anthropic 預先建立和維護 | 透過 Skills API 上傳和管理 |
可用性 | 對所有使用者可用 | 私有於您的工作區 |
source
參數進行篩選)。整合形式和執行環境相同——唯一的區別是 Skills 的來源和管理方式。
先決條件
要使用 Skills,您需要:- Anthropic API 金鑰,來自 Console
- Beta 標頭:
code-execution-2025-08-25
- 啟用程式碼執行(Skills 所需)skills-2025-10-02
- 啟用 Skills APIfiles-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 下載實際檔案內容
- 在本地儲存或根據需要處理
如需 Files API 的完整詳細資訊,請參閱 Files API 文件。
多輪對話
透過指定容器 ID 在多個訊息中重複使用相同的容器:長時間執行的操作
Skills 可能執行需要多個回合的操作。處理pause_turn
停止原因:
回應可能包含
pause_turn
停止原因,這表示 API 暫停了長時間執行的 Skill 操作。您可以在後續請求中按原樣提供回應,讓 Claude 繼續其回合,或修改內容以中斷對話並提供額外指導。使用多個 Skills
在單個請求中結合多個 Skills 以處理複雜工作流程:管理自訂 Skills
建立 Skill
上傳您的自訂 Skill 以在您的工作區中使用。您可以使用目錄路徑或個別檔案物件進行上傳。- 必須在頂層包含 SKILL.md 檔案
- 所有檔案必須在其路徑中指定公共根目錄
- 總上傳大小必須小於 8MB
- YAML 前置事項:
name
(最多 64 個字元)、description
(最多 1024 個字元)
列出 Skills
檢索您的工作區可用的所有 Skills,包括 Anthropic 預先建立的 Skills 和您的自訂 Skills。使用source
參數按 Skill 類型進行篩選:
檢索 Skill
取得特定 Skill 的詳細資訊:刪除 Skill
要刪除 Skill,您必須先刪除其所有版本:版本控制
Skills 支援版本控制以安全地管理更新: Anthropic 管理的 Skills:- 版本使用日期格式:
20251013
- 進行更新時發佈新版本
- 指定確切版本以確保穩定性
- 自動生成的紀元時間戳:
1759178010641129
- 使用
"latest"
始終獲取最新版本 - 更新 Skill 檔案時建立新版本
Skills 如何被載入
當您在容器中指定 Skills 時:- 元資料發現:Claude 在系統提示中看到每個 Skill 的元資料(名稱、描述)
- 檔案載入:Skill 檔案被複製到容器中的
/skills/{directory}/
- 自動使用:Claude 在與您的請求相關時自動載入和使用 Skills
- 組合:多個 Skills 為複雜工作流程組合在一起
使用案例
組織 Skills
品牌與通訊- 將公司特定的格式(顏色、字體、佈局)應用於文件
- 按照組織範本生成通訊
- 確保所有輸出中的一致品牌指南
- 使用公司特定格式(OKR、決策日誌)結構化筆記
- 按照團隊慣例生成任務
- 建立標準化的會議摘要和狀態更新
- 建立公司標準報告、提案和分析
- 執行公司特定的分析程序
- 按照組織範本生成財務模型
個人 Skills
內容建立- 自訂文件範本
- 專業格式和樣式
- 特定領域的內容生成
- 自訂資料處理管道
- 專業視覺化範本
- 行業特定的分析方法
- 程式碼生成範本
- 測試框架
- 部署工作流程
範例:財務建模
結合 Excel 和自訂 DCF 分析 Skills:限制和約束
請求限制
- 每個請求的最大 Skills 數:8
- 最大 Skill 上傳大小:8MB(所有檔案合計)
- YAML 前置事項限制:
name
64 個字元,description
1024 個字元
環境約束
Skills 在程式碼執行容器中執行,具有以下限制:- 無網路存取 - 無法進行外部 API 呼叫
- 無執行時套件安裝 - 僅提供預先安裝的套件
- 隔離環境 - 每個請求都獲得一個新容器
最佳實踐
何時使用多個 Skills
當任務涉及多種文件類型或領域時結合 Skills: 良好的使用案例:- 資料分析 (Excel) + 簡報建立 (PowerPoint)
- 報告生成 (Word) + 匯出為 PDF
- 自訂領域邏輯 + 文件生成
- 包含未使用的 Skills(影響效能)