claude-api

claude-api skill 概覽

claude-api skill 的用途

claude-api skill 是一份用來建構 Claude API 與 Anthropic SDK 整合的實作指南，不是一般性的 prompt 範本包。它會幫你選對整合介面、找到對應語言的正確文件，並用可實際落地的預設做法，快速開始撰寫真正能用的應用程式程式碼。

如果你要把 Claude 加進產品、後端服務、內部工具、CLI 或 agent 工作流程，這個 skill 很適合。若你只是想要一般程式協助，或你的專案是用其他模型供應商的 SDK，那它就不是對的選擇。

誰適合安裝 claude-api

最適合安裝 claude-api 的，是那些想從「我想用 Claude」走到「我已經有正確的 request 結構、SDK 設定與符合我技術棧的工作流程」的開發者。包含：

• 在原始 HTTP、SDK 與 Agent SDK 之間做選擇的 API 開發者
• 要加入 streaming、tool use、files 或 batch processing 的團隊
• 使用 python、typescript、go、java、php、ruby、csharp，或直接用 curl 的開發者

claude-api 有什麼不同

claude-api 的核心價值，在於幫你減少決策成本。它不是把所有內容塞進同一份巨型文件，而是提供：

• 明確的使用邊界：只有當工作明確是 Claude API 或 Anthropic SDK 相關時才使用
• 語言辨識指引，讓你只看和自己專案有關的資料夾
• 實務上可直接採用的預設值，包括 claude-opus-4-6、adaptive thinking，以及適合較長請求的 streaming
• 把相鄰但容易混淆的主題拆開處理，例如 tool use、files API、batches、error codes、models、prompt caching 與 live sources

因此，當你在意的是正確的 SDK 用法與特定功能的實作流程時，claude-api skill 會比泛泛的「給我 API 程式碼」prompt 更有用。

真正要解決的工作

多數使用者並不是想看 repo 導覽，而是想回答這些實際問題：

• 我應該用哪一層：原始 HTTP、Claude API SDK，還是 Agent SDK？
• 以我使用的語言來看，最快速且正確的安裝路徑是什麼？
• 要做 streaming、tools 或較長輸出時，request 應該怎麼設計？
• 我應該先讀哪些檔案，才不會漏掉限制條件或語言支援差異？

當你已經確定要用 Claude，只差一份能少走彎路的實作指引時，這個 skill 最有價值。

如何使用 claude-api skill

安裝 claude-api skill

從 Anthropic skills repository 安裝：

npx skills add https://github.com/anthropics/skills --skill claude-api

安裝後，當你的任務明確涉及下列內容時，就使用 claude-api：

• anthropic
• @anthropic-ai/sdk
• claude_agent_sdk
• Claude API request 設計
• Anthropic SDK migration 或 implementation

如果是不相關的 app 程式碼、ML 理論，或 OpenAI 專用整合，就不要用它。

先從正確的檔案讀起

對多數人來說，最快的閱讀順序是：

1. skills/claude-api/SKILL.md
2. 你的語言資料夾，例如 python/claude-api/README.md 或 typescript/claude-api/README.md
3. 你實際需要的功能檔案：
   • streaming.md
   • tool-use.md
   • files-api.md
   • batches.md
4. 共用參考資料：
   • shared/error-codes.md
   • shared/models.md
   • shared/prompt-caching.md
   • shared/live-sources.md
   • shared/tool-use-concepts.md

這條路徑很重要，因為這個 repository 的結構是依照實作選擇來編排，不是照新手教學流程來排。

先選對整合介面

很多人一開始卡住，不是因為 API 難，而是一開始就選錯介面。

如果你需要在應用程式程式碼裡直接呼叫模型，請用 Claude API SDK 文件。

以下情況則適合先用原始 curl 範例：

• 你需要快速驗證 request shape 是否正確
• 你目前專案使用的語言沒有官方 SDK
• 你想先建立 transport-level 的除錯基準

只有當你在做 agent 工作流程，而且你的語言有支援時，才使用 Agent SDK 文件。在這個 skill 裡，Agent SDK 內容目前有涵蓋 python 與 typescript；其他一些語言則只涵蓋 Claude API 的使用方式。

複製範例前，先判斷語言

claude-api guide 是刻意依語言拆分的。在繼續閱讀或下 prompt 前，先從專案檔案判斷語言，例如：

• package.json, tsconfig.json → TypeScript/JavaScript
• pyproject.toml, requirements.txt → Python
• go.mod → Go
• pom.xml, build.gradle → Java
• composer.json → PHP
• Gemfile → Ruby
• .csproj → C#

這看起來很基本，但能避開一個很常見的失敗情境：你要求的用法其實只存在某個 SDK，另一個 SDK 根本沒有。

有意識地使用內建預設值

SKILL.md 裡的 claude-api usage 指引提供了相當明確的預設：

• model：claude-opus-4-6
• thinking：thinking: {type: "adaptive"}
• 遇到長輸入、長輸出，或高 max_tokens 時使用 streaming

這些預設很有幫助，因為它們能降低 timeout 風險，也能提升第一次產生結果的品質。若你只下了一個模糊 prompt、又把這些條件省略，通常拿到的範例會更短，也比較不像能直接上線的實作。

提供這個 skill 真正需要的最小輸入

想讓 claude-api 產出有用結果，至少要提供：

• 你的語言與 runtime
• 你要的是 Claude API、SDK，還是 Agent SDK
• 你需要的確切功能：basic messages、streaming、tool use、files、batches
• 你的執行環境：local app、server、CLI、cloud function 等
• 任何限制條件：不能 hardcode key、只能 async、框架要求、cloud provider routing

如果沒有這些資訊，輸出通常會停留在泛用層次，也可能忽略不同 SDK 之間的功能可用性差異。

把模糊需求改寫成更有效的 claude-api prompt

較弱的 prompt：

Help me use Claude in my app.

較強的 prompt：

Use the claude-api skill. My project is TypeScript with package.json. I need a server-side example using @anthropic-ai/sdk with claude-opus-4-6, streaming enabled, environment-variable auth, and one tool call for weather lookup. Show install, client setup, the request shape, and basic error handling for 429 and 500.

為什麼這樣效果更好：

• 它先選定了正確資料夾
• 它把整合介面限縮到單一路徑
• 它講清楚哪些功能是必備
• 它要求了會影響整合是否成功的實作細節

依語言使用對應的安裝指令

使用 claude-api skill 的一個實際好處，是它能很快帶出正確的套件名稱：

• C#: dotnet add package Anthropic
• Go: go get github.com/anthropics/anthropic-sdk-go
• PHP: composer require "anthropic-ai/sdk"
• Ruby: gem install anthropic

Java 請使用 com.anthropic:anthropic-java。如果你是走原始 HTTP，請從 curl/examples.md 這條路徑開始。

如果你需要的是 Python 或 TypeScript，請直接進對應語言資料夾的 README.md 與功能文件，不要從其他語言的範例去猜套件怎麼用。

先掌握各語言的重要功能落差

當你在意的是支援能力，而不只是語法時，這個 skill 的價值會特別明顯。

repo 裡能看到的例子包括：

• Go 支援 Claude API 與 beta tool use，但沒有 Agent SDK
• Java 支援 Claude API 與 beta tool use，但沒有 Agent SDK
• Ruby 支援 Claude API 與 beta tool runner，但不支援 Agent SDK
• PHP 支援 Claude API 與多種 client backend，包括 Bedrock、Vertex AI 與 Foundry
• C# 透過 Messages API 支援 tool use，但沒有 class-annotation tool runner

這代表「示範 tool use」本身不是一個完整需求；答案會依語言而不同。

先用 curl 驗證，再除錯 SDK 行為

如果你第一次用 SDK 就失敗，先把 curl/examples.md 裡的原始 HTTP 範例當成對照組。這是整個 repository 裡價值最高的工作流程之一，因為它能幫你拆分問題來源：

• auth 與 endpoint 問題
• JSON 格式錯誤
• model 或參數設定問題
• SDK 特有的 typing 或 serialization 錯誤

repo 也明確建議用 jq 來解析 JSON，而不是 grep 或 sed。這是個小地方，但對可靠性很重要。

及早閱讀共用錯誤處理文件

要上 production 前，先讀 shared/error-codes.md。這份文件不長，但對 claude-api for API Development 很實用，因為它會告訴你哪些錯誤適合重試。

重要例子包括：

• 400 通常代表 request shape 或參數有問題
• 401 與 403 是 auth 或權限問題
• 429、500 與 529 是主要可重試的情況
• 413 表示 request 太大，需要重構，而不是盲目重試

這就是「做出有韌性的整合」和「同一個 request 一直失敗」之間的差別。

claude-api skill 常見問題

claude-api 會比一般 prompt 更好嗎？

會，前提是你的任務屬於實作導向。一般 prompt 也許能產生看起來合理的程式碼，但 claude-api 更擅長把你導到正確的 SDK 介面、語言文件與功能註記，從而減少那些細微卻關鍵的錯誤，例如在不支援的語言裡套用錯誤的 tool-runner 模式。

claude-api 適合初學者嗎？

適合，但前提是你已經懂基本程式設計與 API key 的概念。這個 skill 不是用來取代一般程式教學；它最適合的是已經知道自己技術棧、但不想手動把每個資料夾都讀過一遍，想直接找到正確 Claude 整合路徑的新手。

什麼情況不該用 claude-api？

以下情況請跳過 claude-api：

• 你的任務是一般軟體工程，不是 Claude 整合
• 你的應用本來就圍繞其他 AI provider SDK
• 你需要的是 model-agnostic 架構建議，而不是 Anthropic 專屬實作
• 你做的是 ML training 或 data science，而不是應用整合

claude-api 只涵蓋基本 messages 嗎？

不是。repo 還包含 streaming、tool use、files API、batches、error handling、model references、prompt caching 與 live sources 等聚焦文件。如果你知道專案未來不只會停留在單次 request-response 範例，那麼這些內容會讓 claude-api install 這個決定更值得。

哪些語言的支援最好？

從 repo 目前看得到的結構來看，python、typescript、go、java、php、ruby、csharp 與 curl 都有相當完整的覆蓋。若你的 roadmap 包含 agent 工作流程，Python 與 TypeScript 又多了 Agent SDK 內容，因此會是更合適的選擇。

如何改善 claude-api skill 的使用效果

給 claude-api 更明確的實作背景

提升品質最有效的方法，就是不要再只問「給我一個範例」，而是直接講清楚：

• 語言
• 功能
• framework 或 runtime
• auth 方法
• 部署情境
• 你需要的是直接 SDK 呼叫，還是 agent 行為

例如：

Use claude-api for Python. I need streaming with the Claude API in a FastAPI endpoint, API key from env, graceful handling for 429 and 529, and code structured so I can add tool use later.

這樣得到的會是你能直接延用的程式碼，而不是只能拿來參考的片段。

一次只問一條功能路徑

這個 repository 涵蓋面很廣。如果你一次同時問 streaming、tools、files 與 batches，結果通常會變淺。更好的工作流程是：

1. 先讓最小可用的 messages 範例跑起來
2. 再加 streaming
3. 再加 tool use
4. 需要時再加 files 或 batches
5. 最後補上 retries 與 production guardrails

這個順序和 skill 的組織方式一致，也能有效降低除錯複雜度。

避開常見的 claude-api 失敗模式

最常見的問題其實都很可預期：

• 選錯語言文件
• 以為每個 SDK 都支援相同的 helper abstraction
• 忘了對長回應使用 streaming
• 漏掉 max_tokens
• 在範例裡 hardcode API key
• 把可重試與不可重試的錯誤混為一談

如果你要求 claude-api 明確把這些保護措施加進去，輸出品質通常會好很多。

要求答案明確對齊 repository 內容

想提升 claude-api usage 的實際可用性，一個很有效的方法是要求助理把答案建立在特定 repo 檔案上。例如：

Use claude-api and base the answer on typescript/claude-api/README.md, typescript/claude-api/streaming.md, and shared/error-codes.md. Give me the shortest production-safe starter.

這可以避免答案漂向那種看起來合理、但其實忽略了 skill 結構與限制條件的通用範例程式碼。

在第一版輸出後持續迭代

拿到第一版答案後，再用具體追問去收斂：

• 「把這份改成 raw HTTP，讓我可以除錯 transport 問題。」
• 「依我的 go.mod 改寫，並加上 429 的 backoff。」
• 「把單純 message call 改成這個語言支援的 tool use。」
• 「如果我在 PHP 用 Bedrock 或 Vertex，哪些地方要改？」

這是把 claude-api guide 變成真正可用專案程式碼，而不是一次性 snippet 的最快方式。