--- title: Claude API 技能 url: https://platform.claude.com/docs/zh-TW/agents-and-tools/agent-skills/claude-api-skill description: 一個開源的 Agent Skill，為 Claude 提供最新的 API 參考資料、SDK 文件，以及使用 Claude API 和 Claude Managed Agents 建構應用程式的最佳實務。 --- `claude-api` 技能是一個開源的 [Agent Skill](https://platform.claude.com/docs/zh-TW/agents-and-tools/agent-skills/overview)（代理技能），為 Claude 提供詳細且最新的參考資料，協助您在兩個 Anthropic 介面上建構應用程式： * **Messages API：** 主要介面，適用於單一請求、「streaming」（串流）聊天、「tool use」（工具使用）、「batch processing」（批次處理）、「prompt caching」（提示快取）、「structured outputs」（結構化輸出）以及自訂代理迴圈。 * **Claude Managed Agents（beta）：** 由 Anthropic 託管的介面，提供伺服器管理的有狀態代理，具備由 Anthropic 託管的工具執行、持久化的代理設定，以及每個工作階段專屬的沙箱。 它涵蓋 Messages API 和 Managed Agents 兩者的八種程式語言：Python、TypeScript、C#、Go、Java、PHP、Ruby 和 cURL。 此技能隨 [Claude Code](https://code.claude.com/docs/zh-TW/overview) 一併提供，也可在開源的 [Anthropic 技能儲存庫](https://github.com/anthropics/skills)中取得，您可以將其安裝在任何支援 Agent Skills 的環境中。 此技能使用「[progressive disclosure](https://platform.claude.com/docs/zh-TW/agents-and-tools/agent-skills/overview#how-skills-work)」（漸進式揭露）來保持上下文的效率：Claude 只會載入與您專案的語言、介面（Messages API 或 Managed Agents）以及當前特定任務（工具使用、串流、批次等）相關的文件，而不是一次載入所有內容。 ## 此技能提供的內容 觸發時，此技能會為 Claude 提供： **針對 Messages API：** * **特定語言的 SDK 文件：** 針對您專案語言的安裝、快速入門、常見模式和錯誤處理 * **工具使用指引：** 特定語言的範例，以及函式呼叫的[概念基礎](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/overview)，包括在可用時的 beta tool runner * **串流模式：** 建構聊天 UI 和處理漸進式顯示的實作細節 * **批次處理：** 以 50% 成本進行離線批次處理 * **提示快取：** 前綴穩定性設計、斷點放置，以及靜默失效因素稽核 * **模型遷移：** 遷移至較新 Claude 模型的逐步指引（包括 [Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-5)、[Claude Sonnet 5.5](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5)、[Claude Haiku 5.5](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide) 以及 [Claude Fable 5.1](https://platform.claude.com/docs/zh-TW/models/fable-5-1/migration-guide) 上的重大變更與行為轉變） * **「Preserved thinking」（保留思考）遷移：** 找出、衡量並修正會使 `thinking` 區塊失效的歷史編輯，可透過 `/claude-api preserved-thinking-migration` 子命令使用 * **目前的模型資訊：** 模型 ID、「context window」（上下文視窗）大小和定價 * **常見陷阱：** 關於在與 API 整合時避免常見錯誤的詳細指引 **針對 Managed Agents（beta）：** * **入門流程：** 以訪談方式引導您從頭設定新的 Managed Agent，可透過 `/claude-api managed-agents-onboard` 子命令使用 * **特定語言的 Managed Agents 文件：** 針對 Python、TypeScript、C#、Go、Java、PHP、Ruby 和 cURL，說明如何建立持久化代理、啟動工作階段、串流事件以及處理工具確認 * **用戶端模式：** 無損串流重新連線、`processed_at` 佇列中/已處理閘門、中斷處理、檔案掛載注意事項，以及憑證處理 * **部署限制：** Managed Agents 僅在 Claude API 和 [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws) 上提供（不適用於 Amazon Bedrock、Google Cloud 或 Microsoft Foundry）。對於其他部署，此技能會改為引導至 Messages API 和工具使用。 ## 此技能何時啟用 此技能透過兩種方式啟用： **自動啟用**發生於以下情況： * 您的程式碼匯入了 Anthropic SDK（Python 為 `anthropic`，TypeScript/JavaScript 為 `@anthropic-ai/sdk`） * 您要求 Claude 協助使用 Claude API、Anthropic SDK 或 Managed Agents 建構、除錯或最佳化某些內容 * 您在檔案中新增、修改或調整 Claude 功能（提示快取、自適應思考、壓縮、工具使用、批次、檔案、引用、記憶）或模型參照 **手動呼叫**：在任何已安裝此技能的環境中輸入 `/claude-api`（可搭配選用的子命令或文字描述）。 此技能不會在一般程式設計任務、ML/資料科學工作，或匯入其他 AI SDK（例如 OpenAI）的程式碼中啟用。 ## 支援的語言 此技能會透過檢查專案檔案（例如 Python 的 `requirements.txt`、TypeScript 的 `tsconfig.json`、Go 的 `go.mod`）自動偵測您專案的語言，並載入適當的文件。 | 語言 | Messages API SDK | 工具執行器 | Managed Agents | | ---------- | ---------------- | ------- | -------------- | | Python | 是 | 是（beta） | 是（beta） | | TypeScript | 是 | 是（beta） | 是（beta） | | C# | 是 | 是（beta） | 是（beta） | | Go | 是 | 是（beta） | 是（beta） | | Java | 是 | 是（beta） | 是（beta） | | PHP | 是 | 是（beta） | 是（beta） | | Ruby | 是 | 是（beta） | 是（beta） | | cURL | 是 | 不適用 | 是（beta） | 如果您的專案使用多種語言，Claude 會詢問適用哪一種。對於不支援的語言（Rust、Swift、C++），此技能會提供 cURL/原始 HTTP 範例。 ## 如何使用此技能 ### 在 Claude Code 中（內建） 此技能隨 [Claude Code](https://code.claude.com/docs/zh-TW/overview) 一併提供，無需安裝。當您要求 Claude 協助使用 Claude API 建構某些內容，或您的專案已匯入 Anthropic SDK 時，此技能會自動啟用。 您也可以直接呼叫它： 在 Claude Code 中使用此技能 ```text /claude-api ``` 如需進一步了解內建技能在 Claude Code 中的運作方式，請參閱 [Claude Code 技能文件](https://code.claude.com/docs/zh-TW/skills#bundled-skills)。 ### 從技能儲存庫安裝 此技能的原始碼可在 [Anthropic 技能儲存庫](https://github.com/anthropics/skills)中取得。您可以使用 `npx` 命令安裝： ```bash npx skills add https://github.com/anthropics/skills --skill claude-api ``` 或要求 Claude Code 將其安裝為 [Claude Code 外掛程式](https://code.claude.com/docs/zh-TW/plugins)： 讓 Claude Code 為您安裝 ```text 從 anthropics/skills 外掛程式市集安裝 claude-api 外掛程式 ``` ```text wrap /plugin marketplace add anthropics/skills /plugin install claude-api@anthropic-agent-skills ``` ## 遷移至較新的 Claude 模型 Claude API 技能可以在整個程式碼庫中執行 Claude 模型遷移。使用 `/claude-api migrate` 直接呼叫它： 讓 Claude Code 為您遷移程式碼 ```text /claude-api migrate 將此專案遷移至最新的 Claude Opus 模型 ``` 您也可以預先傳入特定範圍，以略過範圍確認問題： 讓 Claude Code 為您遷移程式碼 ```text /claude-api migrate 將 src/ 下的所有內容遷移至最新的 Claude Opus 模型 ``` 讓 Claude Code 為您遷移程式碼 ```text /claude-api migrate 將 apps/api.py 和 apps/worker.py 遷移至最新的 Claude Opus 模型 ``` 當範圍不明確時（例如單純的 `/claude-api migrate to claude-opus-5-5`），此技能會在編輯任何檔案之前，請您在整個工作目錄、特定子目錄或明確的檔案清單之間做出選擇。這同時適用於 Messages API 和 Managed Agents 的呼叫端。 此技能會處理： * **模型 ID 替換**，包括所有支援語言中的型別化 SDK 常數（`Model.CLAUDE_OPUS_4_8` → `Model.CLAUDE_OPUS_5_5`），並在編輯前將每個檔案分類為呼叫端、模型定義端或不透明字串參照 * **雲端平台偵測**，保留平台特定的模型 ID 格式（例如 Amazon Bedrock 上的 `anthropic.` 前綴），並略過在合作夥伴營運平台上無法使用之功能的變更 * **重大參數變更**，例如針對 Claude Opus 4.8 和 Claude Opus 4.7 移除 `temperature`、`top_p` 和 `top_k`，以及將 `thinking: {type: "enabled", budget_tokens: N}` 轉換為 `thinking: {type: "adaptive"}` * **預填替換**，在適用時將助理訊息預填模式轉換為[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs) * **Beta 標頭清理**，移除目標模型不需要的 beta 標頭（例如 `effort-2025-11-24`、`fine-grained-tool-streaming-2025-05-14`、`interleaved-thinking-2025-05-14`），並從 `client.beta.messages.create()` (go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; csharp: `client.Beta.Messages.Create()`; php: `$client->beta->messages->create()`) 切換回 `client.messages.create()` (go: `client.Messages.New()`; java: `client.messages().create()`; csharp: `client.Messages.Create()`; php: `$client->messages->create()`) * **Effort 校準**，為目標模型建議 `output_config.effort` 的起始值（例如 Claude Opus 5 上的預設值 `high`，以及 Claude Opus 4.8 和 Claude Opus 4.7 上針對程式設計和代理使用案例的 `xhigh`） * **提示行為調整**，標記在目標模型上可能表現不同的長度控制、工具觸發、子代理和指令遵循提示 * **靜默預設值處理**，當在 Claude Opus 4.8 和 Claude Opus 4.7 上向使用者呈現推理內容時，重新選擇啟用思考摘要（`thinking.display: "summarized"`） * **拒絕備援設定**，當目標為 Claude Fable 5.1、Claude Fable 5、Claude Opus 5.5、Claude Opus 5 或 Claude Sonnet 5.5 時，在讀取回應內容之前加入 `stop_reason: "refusal"` 處理，並設定[備援重試路徑](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback)（伺服器端的 `fallbacks` 參數，通常使用其 `"default"` 模式、SDK 拒絕備援中介軟體，或備援抵免重試），以及更新針對較早預覽版結構所撰寫的備援程式碼 在編輯過程中，此技能會以內嵌方式說明每項變更及其動機。完成後，它會產生一份需要手動驗證的項目檢查清單（通常包括整合測試、長度控制提示調整，以及成本/速率限制的重新基準化）。 如需此技能所套用之模型特定變更的完整清單，請參閱[從 Claude Opus 5 遷移至 Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-5)、[從 Claude Opus 4.8 遷移至 Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8)、[從 Claude Sonnet 5 遷移至 Claude Sonnet 5.5](https://platform.claude.com/docs/zh-TW/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5)、[Claude Haiku 5.5 遷移指南](https://platform.claude.com/docs/zh-TW/models/haiku-5-5/migration-guide) 以及 [Claude Fable 5.1 與 Claude Mythos 5.1 遷移指南](https://platform.claude.com/docs/zh-TW/models/fable-5-1/migration-guide)。 ## 針對保留思考檢查整合 「Preserved thinking」（[保留思考](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking)）只有在 `system` 提示、`tools` 以及其之前的訊息保持不變時，才會讓 `thinking` 區塊維持有效。若要找出並修正您的程式碼編輯該歷史記錄的位置，請開啟建構您請求的儲存庫，並呼叫 `preserved-thinking-migration` 子命令： 讓 Claude Code 為您檢查程式碼 ```text /claude-api preserved-thinking-migration ``` 此技能會依序執行五個步驟： 1. **範圍：** 檢查您的整合是否受到影響，然後傳送三個測試請求，以確認 API 會回報刻意的編輯。 2. **找出：** 擷取您自己的幾個多輪工作階段，比對連續請求之間的差異，並列出您的程式碼編輯前綴的每個位置。 3. **衡量：** 使用 `"drop_block"` 重播這些工作階段，並回報哪些對話遺失了 `thinking` 區塊、在哪一輪遺失，以及原因。 4. **修正：** 一次將一項編輯替換為[在不編輯前綴的情況下進行變更](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking#replace-prefix-edits)中對應的模式，並在每次變更後重新衡量。 5. **報告：** 彙整每個原因、針對該原因所做的變更，以及變更前後的計數。 如果您的專案有評估（eval），此技能也會比較有無遺失 `thinking` 區塊時的分數和 token 使用量。 測試請求和重播都是真實的 Messages API 請求，並以模型的一般費率計費。每次重播只請求少量輸出 token，並將 `tool_choice` 設為 `none`，因此不會執行任何工具。此技能會在傳送之前說明成本並徵求您的同意。 ## 設定 Managed Agent 若要從頭建立新的 Managed Agent 架構，請呼叫 `managed-agents-onboard` 子命令： 讓 Claude Code 為您設定代理 ```text /claude-api managed-agents-onboard ``` 此技能會執行一段訪談，引導您了解 Managed Agents 的心智模型（Agent 設定與 Session 的差異）、建立代理設定範本、設定環境和工具、設定工作階段迴圈，並為您的語言產生可執行的程式碼。此技能也涵蓋必要的 **Agent（一次）→ Session（每次執行）** 流程：`model`、`system` 和 `tools` 位於代理上，絕不位於工作階段上，且代理應只建立一次並透過 ID 參照。 Managed Agents 需要 `managed-agents-2026-04-01` beta 標頭，SDK 會為所有 `client.beta.agents.*`、`client.beta.environments.*`、`client.beta.sessions.*` 和 `client.beta.vaults.*` 呼叫自動設定此標頭。 ## 使用範例 以下是此技能協助 Claude 處理的任務範例： **建構聊天應用程式：** 讓 Claude Code 為您建構 ```text 使用 TypeScript 和 Claude API 建構串流聊天 UI ``` **遷移現有專案：** 讓 Claude Code 為您遷移程式碼 ```text /claude-api migrate 將此程式碼庫遷移至最新的 Claude Opus 模型並重新調整 effort ``` **入門設定新的 Managed Agent：** 讓 Claude Code 為您設定代理 ```text /claude-api managed-agents-onboard ``` 在每種情況下，此技能都會載入相關的特定語言文件，並使用目前的 API 模式和最佳實務引導 Claude 完成實作。 ## 後續步驟 了解 Agent Skills 的運作方式以及漸進式揭露模型 瀏覽適用於所有支援語言的官方 Anthropic SDK 探索 GitHub 上公開的 Anthropic 技能儲存庫