add-provider-package_skill

Overview

This skill guides adding a new @ai-sdk/<provider> package to the AI SDK. It explains package layout, implementation patterns, build and test configuration, and the release checklist to integrate an AI service cleanly into the SDK. Follow the steps to implement models, validate responses, add examples, and publish safely.

How this skill works

The guide follows the SDK's adapter-style provider architecture: implement provider instances that produce model classes conforming to the @ai-sdk/provider interfaces, reuse utilities from @ai-sdk/provider-utils, and wire exports and tests so the new package builds in the monorepo. It inspects package.json, TypeScript configs, build settings, test configurations, model interfaces, error handling, and documentation requirements.

When to use it

• When creating a new first- or third-party @ai-sdk/<provider> package to integrate an AI service.
• When implementing language, embedding, or image models for the SDK.
• When adding runtime-safe parsing and validation for provider API responses.
• When preparing package build, tests (Node and Edge), and monorepo references.
• When adding examples and documentation for users of the new provider.

Best practices

• Follow the package structure and naming conventions (kebab-case for files, Provider classes PascalCase).
• Use loadApiKey and provider-utils helpers to load credentials securely.
• Validate API responses with zod schemas; prefer .nullish() for response fields and .optional() for user-facing options.
• Implement model classes that conform to LanguageModelV3, EmbeddingModelV3, ImageModelV1, etc.
• Write both Node and Edge tests and capture API fixtures for parsing tests.
• Create clear examples for each supported model and run full type checks before publishing.

Example use cases

• Add a new language model provider with text generation and streaming support.
• Implement an embeddings provider and provide embed/<provider>.ts example.
• Add an image generation provider with generate-image/<provider>.ts example and response validation.
• Create a provider that supports structured outputs and include generate-object/<provider>.ts example.
• Ship a third-party provider package and link it from docs while following the same tests and build flow.