add-provider-package

add-provider-package skill 概覽

add-provider-package skill 是一份聚焦實作的指南，用來在 vercel/ai 內建立新的 @ai-sdk/<provider> 套件。它特別適合維護者、貢獻者，以及 API 平台團隊：如果你想把某個 model provider 整合進 AI SDK，並且希望套件結構、adapter 分層與 repository 慣例都做對，這個 skill 就很有幫助。

add-provider-package 實際上能幫你完成什麼

真正要解決的問題，不是「寫一些 wrapper code」而已。add-provider-package skill 會協助你新增一個符合 AI SDK 內部架構的 provider package，正確輸出預期的 provider surface，並遵循這個 repo 現有的 package layout、測試策略與實作模式。

哪些人適合使用 add-provider-package

如果你符合以下情境，就適合使用 add-provider-package skill：

• 要在 vercel/ai monorepo 中新增一個 model provider
• 要打造一個比照 first-party packages 的 third-party provider package
• 想把外部 API 對應進 AI SDK 的抽象層，例如 language models 或 embeddings
• 想要的是比泛泛一句「build an adapter」更具體、可落地的路徑

尤其當你已經理解該 provider 的 HTTP API，但還需要協助把它轉成 AI SDK 的 package 慣例時，這個 skill 會特別有價值。

最適合的使用情境

add-provider-package skill 最擅長的情境包括：

• 建立新的 packages/<provider> 資料夾與預期中的結構
• 依照 @ai-sdk/provider 介面實作 provider classes
• 重用既有 providers 的模式，而不是自己發明一套
• 在投入時間前，先弄清楚 first-party 與 third-party 的要求差異

與一般 coding prompt 的關鍵差異

一般 prompt 也能草擬 adapter code；但當你需要具 repository 脈絡的指引時，add-provider-package 會更有價值：例如套件應該放在哪裡、provider architecture 如何分層、通常有哪些檔案，以及在這個 codebase 裡，一個完整的 provider package 應該長什麼樣子。

採用前最重要的限制

這個 skill 的定位本來就很窄。它是為了建立 @ai-sdk/<provider> package，不是用來做一般 API SDK 設計、無關的 wrappers，或任意 plugin system。若你的目標不在 AI SDK 的 provider architecture 內，這個 skill 會顯得過度特化。

如何使用 add-provider-package skill

安裝 add-provider-package skill 的上下文

這個 skill 位於 vercel/ai 的 skills/add-provider-package。在支援 Skills 的工作流程中，可用以下指令安裝：

npx skills add vercel/ai --skill add-provider-package

如果你的環境已經會自動載入 repository skills，也可能只需要直接用名稱呼叫這個 skill。

先看最重要的那個檔案

先讀 skills/add-provider-package/SKILL.md。從這份 repository snapshot 來看，skill 的主要指引集中在這裡，包括：

• first-party 與 third-party package 的期待差異
• 分層式的 provider architecture
• package structure
• 逐步的實作指引
• 可作為完整範例的 reference PR

由於這裡沒有額外露出的 resources/、rules/ 或 helper scripts，所以真正有用的訊號，大多都在 SKILL.md，以及 monorepo 內其他既有 provider packages。

add-provider-package 需要你提供哪些輸入

如果想讓 skill 產出真正有用的結果，請提供具體的 provider 資訊，而不只是「幫 X 加上支援」。最低限度、且有幫助的輸入包括：

• provider 名稱與套件目標，例如 @ai-sdk/acme
• API 驗證方式
• 支援的 model 類型：chat、completion、embeddings、image 等
• streaming 行為
• request 與 response schema
• error 格式與 rate-limit 行為
• 任何 provider 特有的細節，例如 tool calling 或 JSON mode 的差異

缺少這些資訊時，skill 可以幫你列出架構，但無法可靠地把 adapter 形狀定準。

把模糊目標改寫成強 prompt

較弱的 prompt：

Use add-provider-package to add Acme AI to the SDK.

較強的 prompt：

Use add-provider-package to scaffold a new packages/acme provider for vercel/ai. Acme uses API key auth via Authorization: Bearer <key>. It supports text generation and embeddings, with SSE streaming for text. I need the package structure, main source files, likely exports, and the mapping from Acme endpoints to AI SDK model interfaces. Show the repo files I should create first and call out any ambiguous areas I must resolve from the API docs.

這種寫法效果更好，因為它提供了足夠資訊，讓 skill 能選對 provider surface，並且更早暴露尚未解決的整合風險。

建議的 add-provider-package 使用流程

一個實用的 add-provider-package usage 流程如下：

1. 先確認你要做的是 first-party 還是 third-party package。
2. 閱讀 SKILL.md，掌握架構與預期的 package layout。
3. 檢查 skill 中連結的參考 PR：https://github.com/vercel/ai/pull/8136/files。
4. 比對 packages/ 中一到兩個既有 provider packages。
5. 先請 skill 把你的 provider API 對應到 AI SDK 介面，再開始產生檔案。
6. 接著再要求 package skeleton、implementation plan 與 test checklist。

這個順序能減少返工，因為介面不吻合的問題會在 code generation 之前就被抓出來。

讀完 SKILL.md 後，接著該看哪些 repository 路徑

如果你要做出真正的實作判斷，通常最值得接著閱讀的路徑是：

• skills/add-provider-package/SKILL.md
• skill 內連結的 reference PR
• monorepo 中既有的 packages/<provider>/src/* 實作
• @ai-sdk/provider 內的共享介面
• @ai-sdk/provider-utils 中的 helper patterns

這個 skill 已明確說明了這種分層式架構，所以閱讀這些區域，就是拿來驗證產生出的程式碼是否符合 repo 當前模式的最佳方式。

add-provider-package 擅長涵蓋哪些內容

add-provider-package guide 對以下事項特別有幫助：

• package scaffolding
• 在 AI SDK 內的架構適配
• 找出哪些 provider interfaces 真的重要
• 理解如何把 provider 建模成 adapter，而不是一個客製 client
• 把既有 provider 的新增案例當作 reference implementation

它不會替你決定的事

這個 skill 不會讓你省掉解讀上游 provider API 文件的工作。你仍然需要自己判斷：

• 哪些能力值得做成 first-class support
• provider 特有的 request options 要怎麼處理
• 哪些 models 應該被 expose
• 非標準 errors 與 streaming payloads 要怎麼轉譯
• 不支援的功能應該省略，還是透過 provider-specific options 暴露出來

用 add-provider-package for API Development 時，實用的 prompt 方式

如果你是在做 add-provider-package for API Development，建議按決策順序要求輸出：

1. capability mapping
2. package/file plan
3. type/interface plan
4. request/response transformation plan
5. tests and edge cases

範例：

Use add-provider-package to plan an @ai-sdk/zen package. First, map Zen's endpoints to AI SDK interfaces. Second, propose the package file tree. Third, list the core transforms for text generation, embeddings, and streaming. Finally, list the top 10 edge cases to test.

這樣通常比一開始就要求完整 code dump，更容易得到可實作的結果。

開始寫程式前常見的卡點

最大的卡點通常不是 syntax error，而是產品與整合層面的決策還沒釐清：

• 這到底是要做成 first-party 還是 third-party？
• 這個 provider API 真的能乾淨地對應到 AI SDK 抽象嗎？
• streaming events 穩不穩定，足以被 adapter 化嗎？
• 哪些 model capabilities 已經成熟到值得 expose？
• 有沒有 API 形狀更接近的既有 provider 可直接參考？

建議在真正開始建 package 前，就先用這個 skill 把這些問題攤出來。

add-provider-package skill FAQ

add-provider-package 只有 Vercel 維護者才適合用嗎？

不是。這個 skill 對外部貢獻者與 third-party package 作者同樣有用。原始內容已明確區分 third-party packages 與 first-party @ai-sdk/<provider> packages，也提到若是 first-party 新增，應先討論再推進。

add-provider-package 適合新手嗎？

可以用，但前提是你已經熟悉目標 provider 的 API。它不是以新手為導向的 TypeScript、package publishing 或 SDK design 教學。它最大的價值，在於提供 repo-specific guidance 與架構適配上的判斷。

這和直接叫 LLM 寫一個 provider wrapper 有什麼不同？

一般 prompt 可能會產出看起來合理的程式碼，但不一定符合 AI SDK 的 package structure 或 interfaces。add-provider-package skill 會把整個工作錨定在 monorepo 的 adapter architecture 上，並引導你參考具體的 reference implementation。

我可以在 vercel/ai repo 之外使用 add-provider-package 嗎？

可以，作為模式參考是可行的。不過，你的專案越接近 AI SDK 的 provider abstractions 與 package layout，輸出的可轉用性就越高。如果你的 codebase 採用不同的 interfaces 或 publishing conventions，就要預期仍需自行調整。

什麼情況下不該用 add-provider-package？

如果你是以下情境，就建議跳過：

• 在做通用型 API client
• 要整合的 provider 不屬於 AI SDK 模型架構
• 你要找的是 frontend app 範例，而不是 provider package 程式碼
• 你不打算檢查既有 provider 實作來確認一致性

add-provider-package 有包含完整的 end-to-end 範例嗎？

它有提供一個完整 provider 新增案例的 PR 參考：https://github.com/vercel/ai/pull/8136/files。這其實是整個 skill 最有價值的部分之一，因為它直接展示了在實際脈絡中，一個完成版的新增應該長什麼樣子。

如何改進 add-provider-package skill 的使用效果

給 add-provider-package 能力層級的輸入

想最快提升輸出品質，最有效的方法就是更精準地描述 provider 能力。不要只說「supports chat」，而是提供：

• endpoint 名稱
• streaming protocol
• tool calling 支援情況
• structured output 行為
• embeddings 維度或 request 格式
• auth 與 headers
• retry 或 rate-limit 的特殊行為

這樣 skill 才能根據介面適配來推理，而不是從行銷式描述裡猜測。

在產生程式碼前，先要求 gap analysis

一個很好的第一步是：

Use add-provider-package to identify the gaps between this provider API and AI SDK expectations before proposing code.

這通常比立刻要求 scaffolding 更好，因為它會先暴露缺少的功能、不相容的 streaming 格式，或那些必須透過 provider-specific options 處理的區域。

指出一個相似的既有 provider 當參考

如果你知道 vercel/ai 裡有某個 provider 的 API 形狀很接近，請直接講明。例如：

Use add-provider-package and model this after the provider package that has the closest SSE text streaming and embeddings support.

這能提升一致性，也能減少憑空發明抽象的情況。

要求逐檔輸出，而不是一次生成一大包草稿

如果你要求 skill 依檔案拆開輸出，通常更容易驗證，例如：

• package tree
• src/index.ts exports
• provider factory
• model implementation files
• tests
• package metadata

這會比一次生成整個 package，更可靠、更容易審查。

使用 add-provider-package 時要注意的常見失敗模式

使用 add-provider-package 時，請特別檢查輸出是否有以下問題：

• 把尚未穩定支援的能力當成已穩定功能暴露出來
• 對 streaming 的映射過度樂觀
• provider-specific options 滲漏進通用介面
• 缺少 error normalization
• package structure 與既有 repo 慣例不一致
• 程式碼忽略了 first-party 與 third-party 在流程上的差異

用具體 API 範例來強化 prompt

如果第一輪輸出還是太抽象，就補上 provider 文件中的真實 request 與 response 範例。這是最有槓桿的改進方式之一，因為 provider package 的成敗往往取決於 transformation 是否正確。

好的後續 prompt 例如：

Here are the exact JSON request and SSE response shapes for text generation. Revise the add-provider-package plan so the model implementation and streaming parser match these payloads.

明確要求 skill 拆分尚未解決的決策

第一輪完成後，可以再要求 skill 把內容拆成：

• confident implementation steps
• assumptions
• open questions requiring provider docs
• likely tests

這種結構會讓 skill 的輸出更可執行，也能減少把猜測藏在內容裡的情況。

驗證 add-provider-package 輸出的最佳方式

把輸出視為一份具 repository 脈絡的 implementation plan，然後對照以下內容驗證：

• SKILL.md
• 連結的 reference PR
• 一到兩個既有 provider packages
• @ai-sdk/provider interfaces
• 目標 provider 的官方 API docs

這個驗證迴圈，是把 add-provider-package usage 從「有幫助的草稿」提升到「真的能 merge 或 publish 的 package」的最佳方式。