add-provider-package

add-provider-package skill の概要

add-provider-package skill は、vercel/ai 内に新しい @ai-sdk/<provider> パッケージを追加するための、実装に特化したガイドです。単にラッパーを書くためのものではなく、AI SDK のアーキテクチャに沿った形で provider を組み込みたいメンテナー、コントリビューター、API プラットフォームチームに向いています。適切なパッケージ構成、adapter のレイヤリング、リポジトリ慣習に沿って進めたい場合に特に有効です。

add-provider-package で実際にできること

本当に解決してくれるのは、「とりあえず wrapper code を書く」ことではありません。add-provider-package skill は、AI SDK の内部アーキテクチャに自然に収まり、想定された provider surface を export し、このリポジトリのパッケージ構成・テスト方針・実装パターンに沿った provider package を追加するのに役立ちます。

add-provider-package を使うべき人

次のようなケースなら、add-provider-package skill が適しています。

• vercel/ai monorepo に新しい model provider を追加したい
• first-party packages を手本に third-party provider package を作りたい
• 外部 API を AI SDK の abstractions（language models や embeddings など）に落とし込みたい
• 「adapter を作って」で終わる一般論ではなく、具体的な実装の進め方が欲しい

特に、provider 側の HTTP API は理解しているものの、それを AI SDK の package conventions にどう変換すべきかで迷っている人に向いています。

add-provider-package が最もハマるユースケース

add-provider-package skill が強いのは、次のような場面です。

• 想定どおりの構造で新しい packages/<provider> フォルダを作りたい
• @ai-sdk/provider interfaces に沿って provider classes を実装したい
• 独自流儀を持ち込むのではなく、既存 provider のパターンを再利用したい
• 工数をかける前に、first-party と third-party の期待値の違いを把握したい

汎用的な coding prompt との違い

一般的な prompt でも adapter code の草案は作れます。ただし add-provider-package の価値は、リポジトリ前提の具体性にあります。つまり、package をどこに置くのか、provider architecture がどうレイヤー分割されているのか、どんなファイルが通常必要なのか、この codebase で「完成した provider package」がどういう形をしているのかまで踏み込んで案内してくれます。

導入前に理解しておきたい最大の制約

この skill は意図的に用途を絞っています。対象は @ai-sdk/<provider> package の作成であり、一般的な API SDK 設計や無関係な wrapper、任意の plugin system 向けではありません。目的が AI SDK の provider architecture から外れているなら、この skill はかなり限定的に感じるはずです。

add-provider-package skill の使い方

add-provider-package のインストール前提

この skill は vercel/ai の skills/add-provider-package にあります。Skills 対応ワークフローでは、次のコマンドでインストールできます。

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

環境側で repository skills が自動的に使えるようになっている場合は、skill 名を指定して呼び出すだけで足りることもあります。

まず最初に見るべき 1 ファイル

最初に読むべきは skills/add-provider-package/SKILL.md です。このリポジトリのスナップショットを見る限り、主要なガイダンスはここに集約されています。具体的には次の内容です。

• first-party と third-party package の期待値の違い
• レイヤー化された provider architecture
• package structure
• step-by-step implementation guidance
• 完成形の参考になる reference PR

この時点では resources/、rules/、helper scripts などの追加素材は表に出ていないため、有用な情報の大半は SKILL.md と、monorepo 内にある既存 provider packages にあります。

add-provider-package に渡すべき入力

実用的な出力を得るには、「X を追加して」のような抽象的な依頼では不十分です。add-provider-package skill には、provider の具体情報を渡してください。最低限あるとよいのは以下です。

• provider 名と package target（例: @ai-sdk/acme）
• API auth method
• 対応する model types: chat、completion、embeddings、image など
• streaming behavior
• request / response schemas
• error format と rate-limit behavior
• tool calling や JSON mode の違いなど、provider 固有の癖

こうした情報がないと、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 を読んで architecture と期待される package layout を把握する。
3. 参照先の reference example PR を確認する: https://github.com/vercel/ai/pull/8136/files
4. packages/ 内の既存 provider package を 1〜2 個比較する。
5. ファイル生成に入る前に、provider API を AI SDK interfaces にどう対応づけるかを skill に整理させる。
6. その後で package skeleton、implementation plan、test checklist を出してもらう。

この順番にすると、interface の不整合をコード生成前に見つけやすくなり、手戻りを減らせます。

SKILL.md の次に見るべき repository paths

実装判断まで踏み込むなら、次の順で読むのが基本です。

• skills/add-provider-package/SKILL.md
• skill 内からリンクされている reference PR
• monorepo 内の既存 packages/<provider>/src/* 実装
• @ai-sdk/provider の shared interfaces
• @ai-sdk/provider-utils の helper patterns

この skill 自体がこうした layered architecture を明示しているので、生成結果が現在の repo パターンに合っているか検証するには、これらを実際に読むのが近道です。

add-provider-package が得意な範囲

add-provider-package guide が特に役立つのは、次の点です。

• package scaffolding
• AI SDK 内での architectural fit の確認
• どの provider interfaces が重要かの切り分け
• bespoke client ではなく adapter として provider を設計する考え方
• 既存の provider 追加事例を reference implementation として使うこと

add-provider-package が代わりに決めてくれるわけではないこと

この skill を使っても、upstream provider の API docs を読み解く作業はなくなりません。最終的には次の判断が必要です。

• どの capabilities を first-class support にするか
• provider 固有の request options をどう扱うか
• どの models を公開するか
• 非標準な errors や streaming payloads をどう翻訳するか
• 未対応機能を省くべきか、provider-specific options として露出させるべきか

API Development で add-provider-package を使うときの実践的な 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 と 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 の abstractions に無理なく乗るのか？
• streaming events は adapter 化できるほど安定しているのか？
• どの model capabilities が公開できる成熟度にあるのか？
• もっと形の近い既存 provider を手本にすべきではないか？

package を作り始める前に、こうした問いを早めに表面化させるために skill を使うのが有効です。

add-provider-package skill の FAQ

add-provider-package は Vercel のメンテナー専用ですか？

いいえ。外部コントリビューターや third-party package authors にとっても有用です。元の内容でも、third-party packages と first-party @ai-sdk/<provider> packages は明確に区別されており、first-party 追加については先に相談すべきとされています。

add-provider-package は初心者向けですか？

対象 provider の API を理解している初心者であれば使えます。ただし、TypeScript、package publishing、SDK design を基礎から教える入門チュートリアルではありません。価値が最大化するのは、repo 固有の作法や architectural fit が必要な人です。

LLM に provider wrapper を作らせるのと何が違いますか？

通常の prompt でも、それらしく見えるコードは出てきます。ただし AI SDK の package structure や interfaces に合っているとは限りません。add-provider-package skill は、作業の軸を monorepo の adapter architecture に固定し、さらに具体的な reference implementation まで示してくれます。

add-provider-package は vercel/ai の外でも使えますか？

はい、パターン参照としては使えます。ただし、あなたのプロジェクトが AI SDK の provider abstractions や package layout に近いほど、出力はそのまま流用しやすくなります。コードベースの interfaces や publishing conventions が違う場合は、当然調整が必要です。

add-provider-package を使わないほうがよいのはどんなときですか？

次のような場合は無理に使わないほうがよいでしょう。

• 汎用的な API client を作っている
• AI SDK モデル以外の形で provider を統合したい
• provider package code ではなく frontend app examples を探している
• 整合性確認のために既存 provider 実装を読むつもりがない

add-provider-package には end-to-end の完全な例が含まれますか？

完全な provider 追加例そのものを埋め込んでいるわけではありませんが、PR ベースの reference への導線があります: https://github.com/vercel/ai/pull/8136/files。実際、この skill の中でも特に価値が高いのがこの部分で、完成した追加がコンテキストの中でどう見えるかを確認できます。

add-provider-package skill を改善する方法

add-provider-package には capability 単位で情報を渡す

出力品質を最も早く改善する方法は、provider の capabilities を精密に伝えることです。「chat をサポート」だけではなく、次のように具体化してください。

• endpoint names
• streaming protocol
• tool calling support
• structured output behavior
• embeddings の dimensionality や request format
• auth と headers
• retry や rate-limit 周りの癖

これにより、skill は marketing 用語から推測するのではなく、interface fit を根拠を持って判断できます。

コード生成の前に gap analysis を依頼する

最初の一手として有効なのは次の依頼です。

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

いきなり scaffolding を求めるより有効なことが多く、未対応機能、互換性の低い streaming format、provider-specific options が必要になる箇所などを先に洗い出せます。

似た既存 provider を明示して参照させる

vercel/ai 内で API の形が近い provider を知っているなら、最初から伝えましょう。たとえば次のように依頼できます。

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

こうすると一貫性が上がり、不要な独自 abstraction も減らせます。

巨大な一括出力ではなく、ファイルごとに出してもらう

次のように、粒度を分けて依頼したほうが add-provider-package の結果は検証しやすくなります。

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

パッケージ全体を一度に生成させるより、レビューの信頼性が上がります。

add-provider-package でよくある失敗パターン

add-provider-package を使う際は、次のような点を重点的に確認してください。

• 未成熟な capabilities が、安定機能のように露出していないか
• streaming の対応づけが楽観的すぎないか
• provider 固有 options が generic interfaces に漏れていないか
• error normalization が抜けていないか
• package structure が既存 repo conventions とずれていないか
• first-party / third-party のプロセス差を無視したコードになっていないか

実際の API サンプルを追加して prompt を改善する

最初の出力が抽象的すぎるなら、provider docs にある実際の request / response samples を渡してください。これは改善効果が非常に大きいやり方です。provider package は transformation の正確さがそのまま品質に直結するからです。

良い follow-up 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.

未解決の判断を明示的に切り分けて反復する

最初の結果を受けて、次の区分で分けて出してもらうと有効です。

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

この形にすると、skill の出力を実際の作業に落とし込みやすくなり、見えない推測も減らせます。

add-provider-package の出力を検証する最善の方法

出力は「repo を前提にした implementation plan」として受け取り、次の情報源と照合してください。

• SKILL.md
• リンクされている reference PR
• 既存の provider packages を 1〜2 個
• @ai-sdk/provider interfaces
• 対象 provider の公式 API docs

この検証ループこそが、add-provider-package usage を「役に立つ下書き」から、実際に merge や publish できる package に引き上げる最短ルートです。