add-provider-package

Descripción general de la skill add-provider-package

La skill add-provider-package es una guía de implementación muy enfocada para crear un nuevo paquete @ai-sdk/<provider> dentro de vercel/ai. Es especialmente útil para maintainers, contributors y equipos de plataformas API que quieran integrar un proveedor de modelos en el AI SDK con la forma de paquete correcta, la capa de adaptadores adecuada y las convenciones del repositorio.

Lo que add-provider-package realmente te ayuda a hacer

La necesidad real aquí no es simplemente “escribir un wrapper”. La skill add-provider-package te ayuda a añadir un paquete de proveedor que encaje con la arquitectura interna del AI SDK, exporte la superficie de proveedor esperada y siga la estructura de paquetes, la estrategia de tests y los patrones de implementación del repo.

Quién debería usar add-provider-package

Usa la skill add-provider-package si estás:

• Añadiendo un nuevo proveedor de modelos al monorepo vercel/ai
• Creando un paquete de proveedor de terceros inspirado en los paquetes first-party
• Intentando mapear una API externa a abstracciones del AI SDK como modelos de lenguaje o embeddings
• Buscando un camino concreto más allá de un prompt genérico del tipo “build an adapter”

Resulta especialmente útil si ya entiendes la API HTTP del proveedor, pero necesitas ayuda para traducirla a las convenciones de paquetes del AI SDK.

Casos de uso donde add-provider-package encaja mejor

La skill add-provider-package destaca especialmente cuando necesitas:

• Crear una nueva carpeta packages/<provider> con la estructura esperada
• Implementar clases de proveedor sobre las interfaces de @ai-sdk/provider
• Reutilizar patrones de proveedores existentes en lugar de inventar los tuyos
• Entender las expectativas para first-party vs third-party antes de invertir tiempo

Diferencias clave frente a un prompt genérico de código

Un prompt genérico puede redactar código de adaptador. add-provider-package aporta más valor cuando necesitas guía consciente del repositorio: dónde vive el paquete, cómo se organiza por capas la arquitectura del proveedor, qué archivos suelen existir y cómo debe verse un paquete de proveedor completo en este codebase.

La restricción de adopción más importante

Esta skill es deliberadamente específica. Está pensada para crear paquetes @ai-sdk/<provider>, no para diseñar SDKs de API en general, wrappers no relacionados ni sistemas de plugins arbitrarios. Si tu objetivo queda fuera de la arquitectura de proveedores del AI SDK, esta skill te resultará demasiado específica.

Cómo usar la skill add-provider-package

Contexto de instalación para add-provider-package

Esta skill vive en vercel/ai, dentro de skills/add-provider-package. En un flujo de trabajo con Skills activado, se instala con:

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

Si tu entorno ya expone automáticamente las skills del repositorio, puede que solo necesites invocarla por nombre.

Empieza por el archivo que realmente importa

Lee primero skills/add-provider-package/SKILL.md. En este snapshot del repositorio se ve que la orientación principal de la skill se concentra ahí, incluyendo:

• expectativas para paquetes first-party vs third-party
• la arquitectura por capas del proveedor
• la estructura del paquete
• una guía de implementación paso a paso
• un PR de referencia con un ejemplo completo

Como aquí no aparecen resources/, rules/ ni scripts auxiliares adicionales, la mayor parte del valor práctico está en SKILL.md y en los paquetes de proveedores existentes en otras partes del monorepo.

Qué información necesita add-provider-package de tu parte

Para obtener una salida útil, dale a la skill detalles concretos del proveedor, no solo algo como “añade soporte para X”. Los datos mínimos realmente útiles son:

• nombre del proveedor y destino del paquete, por ejemplo @ai-sdk/acme
• método de autenticación de la API
• tipos de modelo compatibles: chat, completion, embeddings, image, etc.
• comportamiento del streaming
• esquemas de request y response
• formato de errores y comportamiento ante rate limits
• peculiaridades específicas del proveedor, como diferencias en tool calling o JSON mode

Sin esos detalles, la skill puede esbozar la estructura, pero no puede dar forma al adaptador de manera fiable.

Convierte un objetivo difuso en un prompt sólido

Prompt débil:

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

Prompt más sólido:

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.

Esto funciona mejor porque le da a la skill suficiente información para elegir la superficie de proveedor correcta y señalar pronto los riesgos de integración aún no resueltos.

Flujo de trabajo recomendado para usar add-provider-package

Un flujo práctico de uso de add-provider-package sería:

1. Confirmar si apuntas a un paquete first-party o third-party.
2. Leer SKILL.md para entender la arquitectura y la estructura de paquete esperada.
3. Revisar el PR de referencia enlazado: https://github.com/vercel/ai/pull/8136/files.
4. Comparar uno o dos paquetes de proveedor existentes en packages/.
5. Pedir a la skill que mapee la API de tu proveedor a las interfaces del AI SDK antes de generar archivos.
6. Después, pedir un esqueleto del paquete, un plan de implementación y un checklist de tests.

Esta secuencia reduce retrabajo porque detecta incompatibilidades de interfaz antes de generar código.

Rutas del repositorio que conviene inspeccionar después de SKILL.md

Para tomar decisiones reales de implementación, la mejor ruta de lectura a continuación suele ser:

• skills/add-provider-package/SKILL.md
• el PR de referencia enlazado dentro de la skill
• implementaciones existentes en packages/<provider>/src/* dentro del monorepo
• interfaces compartidas en @ai-sdk/provider
• patrones auxiliares en @ai-sdk/provider-utils

La skill describe explícitamente esta arquitectura por capas, así que leer esas zonas es la forma de validar el código generado frente a los patrones actuales del repo.

Lo que add-provider-package cubre bien

La guía add-provider-package resulta especialmente útil para:

• scaffolding del paquete
• encaje arquitectónico dentro del AI SDK
• identificar qué interfaces de proveedor importan
• entender cómo modelar un proveedor como adaptador en lugar de como cliente ad hoc
• usar la incorporación de un proveedor existente como implementación de referencia

Lo que no decide por ti

La skill no elimina la necesidad de interpretar la documentación de la API del proveedor original. Sigues teniendo que decidir:

• qué capacidades merecen soporte de primer nivel
• cómo gestionar opciones de request específicas del proveedor
• qué modelos exponer
• cómo traducir errores no estándar y payloads de streaming
• si las funciones no compatibles deben omitirse o exponerse mediante opciones específicas del proveedor

Patrones de prompt prácticos para add-provider-package en API Development

Si estás usando add-provider-package for API Development, pide los resultados en orden de decisión:

1. mapeo de capacidades
2. plan de paquete/archivos
3. plan de tipos/interfaces
4. plan de transformación de request/response
5. tests y casos límite

Ejemplo:

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.

Esto produce un resultado más implementable que pedir desde el principio un gran volcado de código completo.

Bloqueos habituales antes de empezar a programar

Los mayores bloqueos no suelen ser errores de sintaxis, sino decisiones de producto que aún faltan:

• ¿Esto está pensado como first-party o third-party?
• ¿La API del proveedor realmente encaja de forma limpia con las abstracciones del AI SDK?
• ¿Los eventos de streaming son lo bastante estables como para adaptarlos?
• ¿Qué capacidades del modelo están lo bastante maduras como para exponerlas?
• ¿Hay proveedores existentes con una forma más parecida que deberías copiar?

Usa la skill pronto para sacar a la luz estas preguntas antes de construir el paquete.

FAQ de la skill add-provider-package

¿add-provider-package es solo para maintainers de Vercel?

No. La skill también es útil para contributors externos y autores de paquetes third-party. La fuente distingue explícitamente los paquetes de terceros de los paquetes first-party @ai-sdk/<provider> y señala que las incorporaciones first-party deberían comentarse antes.

¿add-provider-package es buena para principiantes?

La pueden usar principiantes que ya conozcan la API del proveedor objetivo, pero no es un tutorial pensado ante todo para aprender TypeScript, publicación de paquetes o diseño de SDKs. Su valor es mayor para quienes necesitan guía específica del repo y encaje arquitectónico.

¿En qué se diferencia esto de pedirle a un LLM que construya un wrapper de proveedor?

Un prompt normal puede generar código aparentemente correcto sin respetar la estructura de paquete ni las interfaces del AI SDK. La skill add-provider-package aterriza el trabajo en la arquitectura de adaptadores del monorepo y te dirige a una implementación de referencia concreta.

¿Puedo usar add-provider-package fuera del repo vercel/ai?

Sí, como referencia de patrón. Pero cuanto más se parezca tu proyecto a las abstracciones de proveedor y a la estructura de paquetes del AI SDK, más transferible será la salida. Si tu codebase usa interfaces o convenciones de publicación distintas, tendrás que adaptar parte del resultado.

¿Cuándo no debería usar add-provider-package?

Sáltatela si estás:

• construyendo un cliente de API de propósito general
• integrando un proveedor fuera del modelo del AI SDK
• buscando ejemplos de apps frontend en lugar de código de paquetes de proveedor
• sin disposición a inspeccionar implementaciones de proveedores existentes para mantener paridad

¿add-provider-package incluye un ejemplo completo end-to-end?

Incluye una referencia a una incorporación completa de proveedor mediante PR: https://github.com/vercel/ai/pull/8136/files. Esa es una de las partes más valiosas de la skill porque muestra cómo se ve una incorporación terminada dentro de su contexto real.

Cómo mejorar la skill add-provider-package

Dale a add-provider-package inputs a nivel de capacidad

La forma más rápida de mejorar la calidad de la salida es describir con precisión las capacidades del proveedor. En lugar de “supports chat”, indica:

• nombres de endpoints
• protocolo de streaming
• soporte para tool calling
• comportamiento de structured output
• dimensionalidad de embeddings o formato de request
• auth y headers
• peculiaridades de retry o rate limit

Esto permite que la skill razone sobre el encaje de interfaces en lugar de adivinar a partir de términos de marketing.

Pide un gap analysis antes de generar código

Un buen primer paso es:

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

A menudo esto funciona mejor que pedir scaffolding de inmediato, porque saca a la luz funciones ausentes, formatos de streaming incompatibles o zonas que requieren opciones específicas del proveedor.

Haz referencia a un proveedor existente parecido

Si conoces un proveedor en vercel/ai con una forma de API similar, dilo. Por ejemplo:

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

Esto mejora la consistencia y reduce abstracciones inventadas.

Pide salida archivo por archivo, no un borrador gigante

La skill es más fácil de validar si pides:

• árbol del paquete
• exports de src/index.ts
• factoría del proveedor
• archivos de implementación del modelo
• tests
• metadatos del paquete

Así la revisión es más fiable que generando el paquete entero de una sola vez.

Modos de fallo habituales que conviene vigilar

Al usar add-provider-package, revisa las salidas para detectar:

• capacidades no compatibles expuestas como si fueran estables
• streaming mapeado con demasiado optimismo
• opciones específicas del proveedor filtrándose en interfaces genéricas
• falta de normalización de errores
• estructura de paquete que no coincide con las convenciones existentes del repo
• código que ignora las diferencias de proceso entre first-party y third-party

Mejora los prompts con muestras concretas de la API

Si la primera salida es demasiado abstracta, añade ejemplos reales de request y response tomados de la documentación del proveedor. Es una de las mejoras de mayor impacto, porque estos paquetes de proveedor dependen por completo de la corrección en las transformaciones.

Buen prompt de seguimiento:

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.

Itera de forma explícita sobre las decisiones no resueltas

Después de la primera pasada, pide a la skill que separe:

• pasos de implementación con alta confianza
• supuestos
• preguntas abiertas que requieren consultar la documentación del proveedor
• tests probables

Esa estructura hace que la skill sea más accionable y reduce las suposiciones ocultas.

La mejor forma de validar la salida de add-provider-package

Trata la salida como un plan de implementación consciente del repo y luego valídala frente a:

• SKILL.md
• el PR de referencia enlazado
• uno o dos paquetes de proveedor existentes
• interfaces de @ai-sdk/provider
• la documentación oficial de la API del proveedor objetivo

Ese bucle de validación es la mejor forma de llevar el uso de add-provider-package desde un “borrador útil” hasta un paquete que realmente puedas fusionar o publicar.