add-provider-package

Présentation de la skill add-provider-package

La skill add-provider-package est un guide d’implémentation ciblé pour créer un nouveau package @ai-sdk/<provider> dans vercel/ai. Elle s’adresse surtout aux mainteneurs, aux contributeurs et aux équipes plateforme API qui veulent intégrer un fournisseur de modèles dans l’AI SDK avec la bonne structure de package, le bon découpage en couches d’adaptation et le respect des conventions du dépôt.

Ce que add-provider-package vous aide réellement à faire

Le vrai besoin ne se résume pas à « écrire un peu de code wrapper ». La skill add-provider-package vous aide à ajouter un package provider conforme à l’architecture interne de l’AI SDK, qui expose la surface provider attendue et suit l’organisation des packages, la stratégie de test et les patterns d’implémentation du dépôt.

À qui s’adresse add-provider-package

Utilisez la skill add-provider-package si vous êtes dans l’un de ces cas :

• vous ajoutez un nouveau provider de modèles au monorepo vercel/ai
• vous construisez un package provider tiers calqué sur les packages first-party
• vous cherchez à faire correspondre une API externe aux abstractions de l’AI SDK, comme les language models ou les embeddings
• vous voulez une démarche concrète qui va au-delà d’un simple prompt du type « build an adapter »

Elle est particulièrement utile si vous comprenez déjà l’API HTTP du provider, mais avez besoin d’aide pour la traduire dans les conventions de package de l’AI SDK.

Cas d’usage où add-provider-package est le plus pertinent

La add-provider-package skill est la plus efficace lorsque vous devez :

• créer un nouveau dossier packages/<provider> avec la structure attendue
• implémenter des classes provider conformes aux interfaces de @ai-sdk/provider
• réutiliser les patterns de providers existants au lieu d’inventer votre propre approche
• comprendre les attentes first-party vs third-party avant d’y investir du temps

Ce qui la distingue d’un prompt de code générique

Un prompt générique peut produire une première ébauche de code d’adaptation. add-provider-package devient plus utile dès que vous avez besoin d’un guidage ancré dans le dépôt : où placer le package, comment l’architecture provider est organisée en couches, quels fichiers existent en général, et à quoi ressemble un package provider complet dans cette codebase.

La contrainte d’adoption la plus importante

Cette skill est volontairement spécialisée. Elle sert à créer des packages @ai-sdk/<provider>, pas à concevoir un SDK d’API généraliste, des wrappers sans rapport, ou des systèmes de plugins arbitraires. Si votre objectif sort de l’architecture provider de l’AI SDK, elle vous paraîtra trop spécifique.

Comment utiliser la skill add-provider-package

Contexte d’installation pour add-provider-package

Cette skill se trouve dans vercel/ai, sous skills/add-provider-package. Dans un workflow compatible Skills, installez-la avec :

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

Si votre environnement expose déjà automatiquement les skills du dépôt, il peut suffire de l’invoquer par son nom.

Commencez par le seul fichier vraiment essentiel

Lisez d’abord skills/add-provider-package/SKILL.md. Dans cet instantané du dépôt, l’essentiel des recommandations de la skill est concentré dans ce fichier, notamment :

• les attentes pour les packages first-party vs third-party
• l’architecture provider en couches
• la structure du package
• un guide d’implémentation pas à pas
• une PR de référence servant d’exemple complet

Comme aucun dossier resources/, rules/ ni script helper supplémentaire n’apparaît ici, la majeure partie de la valeur se trouve dans SKILL.md et dans les packages provider existants ailleurs dans le monorepo.

Les informations que add-provider-package attend de vous

Pour obtenir une sortie utile, donnez à la skill des détails concrets sur le provider, pas juste « add support for X ». Les entrées minimales vraiment utiles sont :

• le nom du provider et la cible de package, par exemple @ai-sdk/acme
• la méthode d’authentification de l’API
• les types de modèles pris en charge : chat, completion, embeddings, image, etc.
• le comportement de streaming
• les schémas de requête et de réponse
• le format des erreurs et le comportement de rate limit
• les particularités du provider, comme le tool calling ou des différences de mode JSON

Sans ces éléments, la skill peut proposer une structure, mais pas façonner l’adapter de manière fiable.

Transformer un objectif vague en prompt solide

Prompt faible :

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

Prompt plus solide :

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.

Cette formulation fonctionne mieux parce qu’elle donne à la skill assez d’informations pour choisir la bonne surface provider et faire remonter tôt les risques d’intégration encore non résolus.

Workflow recommandé pour utiliser add-provider-package

Un workflow pratique pour add-provider-package usage ressemble à ceci :

1. Vérifiez d’abord si vous visez un package first-party ou third-party.
2. Lisez SKILL.md pour comprendre l’architecture et la structure de package attendue.
3. Consultez l’exemple de PR de référence : https://github.com/vercel/ai/pull/8136/files.
4. Comparez un ou deux packages provider existants dans packages/.
5. Demandez à la skill de faire correspondre l’API de votre provider aux interfaces de l’AI SDK avant de générer les fichiers.
6. Demandez ensuite un squelette de package, un plan d’implémentation et une checklist de tests.

Cette séquence limite les allers-retours, car les incompatibilités d’interface sont détectées avant la génération de code.

Chemins du dépôt à inspecter après SKILL.md

Pour prendre de vraies décisions d’implémentation, le meilleur ordre de lecture ensuite est généralement :

• skills/add-provider-package/SKILL.md
• la PR de référence liée dans la skill
• les implémentations existantes dans packages/<provider>/src/* du monorepo
• les interfaces partagées dans @ai-sdk/provider
• les patterns utilitaires dans @ai-sdk/provider-utils

La skill décrit explicitement cette architecture en couches ; lire ces zones est donc la meilleure façon de valider le code généré par rapport aux patterns actuels du dépôt.

Ce que add-provider-package couvre bien

Le add-provider-package guide est particulièrement utile pour :

• le scaffolding du package
• l’intégration architecturale dans l’AI SDK
• l’identification des interfaces provider qui comptent vraiment
• la compréhension d’un provider comme adapter, plutôt que comme client sur mesure
• l’utilisation d’un ajout de provider existant comme implémentation de référence

Ce que la skill ne décide pas à votre place

La skill ne vous dispense pas d’interpréter la documentation API du provider en amont. Vous devez encore décider :

• quelles capacités méritent un support de premier niveau
• comment gérer les options de requête spécifiques au provider
• quels modèles exposer
• comment traduire des erreurs non standard et des payloads de streaming atypiques
• s’il faut omettre les fonctionnalités non prises en charge ou les exposer via des options spécifiques au provider

Modèles de prompt pratiques pour add-provider-package for API Development

Si vous utilisez add-provider-package for API Development, demandez les résultats dans l’ordre des décisions à prendre :

1. mapping des capacités
2. plan package/fichiers
3. plan types/interfaces
4. plan de transformation requête/réponse
5. tests et edge cases

Exemple :

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.

Cette approche produit un résultat plus directement exploitable que de demander d’emblée un dump de code complet.

Blocages fréquents avant même de coder

Les principaux blocages ne sont généralement pas des erreurs de syntaxe, mais des décisions produit non tranchées :

• Est-ce censé être first-party ou third-party ?
• L’API du provider correspond-elle vraiment proprement aux abstractions de l’AI SDK ?
• Les événements de streaming sont-ils assez stables pour être adaptés ?
• Quelles capacités des modèles sont assez mûres pour être exposées ?
• Existe-t-il déjà un provider dont la forme est plus proche et qu’il vaudrait mieux reprendre ?

Utilisez la skill tôt pour faire émerger ces questions avant de construire le package.

FAQ sur la skill add-provider-package

add-provider-package est-elle réservée aux mainteneurs Vercel ?

Non. La skill est aussi utile aux contributeurs externes et aux auteurs de packages tiers. La source distingue explicitement les packages third-party des packages first-party @ai-sdk/<provider> et précise que les ajouts first-party doivent d’abord être discutés.

add-provider-package convient-elle aux débutants ?

Elle peut être utilisée par des débutants qui connaissent déjà l’API du provider ciblé, mais ce n’est pas un tutoriel d’initiation à TypeScript, à la publication de packages ou au design d’un SDK. Sa valeur est maximale pour les personnes qui ont besoin d’un guidage spécifique au dépôt et d’un bon alignement architectural.

En quoi est-ce différent de demander à un LLM de construire un wrapper provider ?

Un prompt classique peut générer du code plausible sans respecter la structure de package ni les interfaces de l’AI SDK. La add-provider-package skill ancre le travail dans l’architecture d’adapters du monorepo et vous oriente vers une implémentation de référence concrète.

Peut-on utiliser add-provider-package en dehors du repo vercel/ai ?

Oui, comme référence de pattern. Mais plus votre projet se rapproche des abstractions provider et de l’organisation des packages de l’AI SDK, plus le résultat sera réutilisable tel quel. Si votre codebase repose sur d’autres interfaces ou d’autres conventions de publication, prévoyez un travail d’adaptation.

Quand ne faut-il pas utiliser add-provider-package ?

Passez votre chemin si vous :

• construisez un client API généraliste
• intégrez un provider en dehors du modèle AI SDK
• cherchez des exemples d’app frontend plutôt que du code de package provider
• n’êtes pas prêt à inspecter les implémentations de providers existantes pour viser la parité

add-provider-package inclut-elle un exemple complet de bout en bout ?

Elle inclut un pointeur de référence vers un ajout complet de provider via une PR : https://github.com/vercel/ai/pull/8136/files. C’est l’un des éléments les plus utiles de la skill, car il montre à quoi ressemble un ajout terminé dans son contexte réel.

Comment améliorer la skill add-provider-package

Donnez à add-provider-package des entrées au niveau des capacités

Le moyen le plus rapide d’améliorer la qualité des résultats consiste à décrire précisément les capacités du provider. Au lieu de dire « supports chat », fournissez :

• les noms des endpoints
• le protocole de streaming
• le support du tool calling
• le comportement de sortie structurée
• la dimension des embeddings ou le format des requêtes
• l’authentification et les headers
• les particularités de retry ou de rate limit

Cela permet à la skill de raisonner sur l’adéquation avec les interfaces, au lieu de deviner à partir de termes marketing.

Demandez une analyse des écarts avant de générer du code

Un très bon premier pas est :

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

C’est souvent préférable à une demande immédiate de scaffolding, car cela fait ressortir les fonctionnalités manquantes, les formats de streaming incompatibles ou les zones qui nécessitent des options spécifiques au provider.

Référencez un provider existant proche

Si vous connaissez dans vercel/ai un provider dont la forme d’API est similaire, dites-le. Par exemple :

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

Cela améliore la cohérence et réduit les abstractions inventées.

Demandez une sortie fichier par fichier, pas un gros brouillon unique

La skill est plus facile à valider si vous demandez :

• l’arborescence du package
• les exports de src/index.ts
• la factory provider
• les fichiers d’implémentation des modèles
• les tests
• les métadonnées du package

Cette approche rend la revue plus fiable que la génération d’un package entier en une seule passe.

Modes d’échec fréquents à surveiller

Quand vous utilisez add-provider-package, vérifiez notamment si les sorties présentent :

• des capacités non prises en charge exposées comme si elles étaient stables
• un mapping du streaming trop optimiste
• des options spécifiques au provider qui fuient dans des interfaces génériques
• une normalisation des erreurs absente
• une structure de package qui ne correspond pas aux conventions existantes du dépôt
• du code qui ignore les différences de processus entre first-party et third-party

Améliorez vos prompts avec des exemples d’API concrets

Si la première réponse est trop abstraite, ajoutez de vrais exemples de requêtes et de réponses issus de la documentation du provider. C’est l’un des leviers les plus puissants, car un package provider se joue souvent sur la justesse des transformations.

Bon prompt de suivi :

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.

Itérez explicitement sur les décisions non résolues

Après un premier passage, demandez à la skill de séparer :

• les étapes d’implémentation fiables
• les hypothèses
• les questions ouvertes nécessitant la documentation du provider
• les tests probables

Cette structure rend la skill plus exploitable et limite les suppositions implicites.

Meilleure manière de valider la sortie de add-provider-package

Considérez la sortie comme un plan d’implémentation conscient du dépôt, puis validez-la par rapport à :

• SKILL.md
• la PR de référence liée
• un ou deux packages provider existants
• les interfaces de @ai-sdk/provider
• la documentation API officielle du provider ciblé

Cette boucle de validation est la meilleure façon de faire passer add-provider-package usage du stade de « brouillon utile » à celui d’un package réellement prêt à être fusionné ou publié.