SkillAgentSearch skills...

add-provider-package

Guide for adding first-party AI provider packages to the AI SDK

Install / Use

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

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

94/100

Category

Security

Supported Platforms

Universal

Our assessment of add-provider-package

add-provider-package scores 94/100 on our quality scale, 312th of 1,111 Security skills we index (top 29%).

Its SKILL.md is 12 KB long, well organised into 14 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.

With 26,924 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
18/20
Description
12/15
Adoption
19/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so add-provider-package is actively maintained.
  • Our last check on 2026-11-16 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-26. Automated pattern scan on 2026-09-26. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

add-provider-package compared with similar skills

All 4 of these similar skills score higher than add-provider-package; compare them before choosing.

SkillScoreStarsUpdatedFormat
add-provider-package (this skill)by vercel9426.9k53d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.md

Frequently asked questions

How do I install add-provider-package?
Run npx skills add vercel/ai --skill add-provider-package. The install tabs above show the steps for each supported agent.
Which AI agents does add-provider-package work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is add-provider-package safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is add-provider-package still maintained?
The repository was last updated about 2 months ago, so add-provider-package is actively maintained.

name: add-provider-package description: Guide for adding first-party AI provider packages to the AI SDK. Use when creating a provider package under packages/ to integrate an external AI service. metadata: internal: true

Add a Provider Package

Add a complete first-party @ai-sdk/<provider> package that follows the current provider interfaces, repository conventions, security requirements, and release process.

Read the Current Sources of Truth

Before implementing anything, read:

Use PR #18595 as a recent end-to-end example, but choose the current provider package whose API shape and model types most closely resemble the new provider as the implementation reference.

Third parties can publish provider packages outside this repository. A new first-party @ai-sdk/<provider> package requires prior discussion in an issue. Confirm that agreement exists before implementing the package.

Discover the API Contract

Before designing model classes, look for an official, versioned OpenAPI or Swagger specification in the provider's documentation or repositories. Prefer first-party specifications and record the source URL plus its version, publication date, or commit in the implementation notes or pull request.

Use the specification and official documentation to identify:

  • base URLs and authentication schemes
  • supported endpoints, model types, and capabilities
  • request parameters and response shapes
  • streaming transports and event formats
  • error response envelopes
  • asynchronous polling and download URL flows

Treat an OpenAPI specification as implementation evidence, not unquestioned truth. Specifications are often incomplete for server-sent events, streaming deltas, polymorphic content, tool calls, nullable fields, and errors. Do not add a generated client or generated production types by default. Implement minimal hand-written types and Zod schemas, then verify them against official documentation and captured API responses.

If no official specification exists, derive the contract from official documentation and real response fixtures, and note that limitation in the pull request.

Plan the Provider Shape

Determine which AI SDK model interfaces the provider supports, such as LanguageModelV4, EmbeddingModelV4, ImageModelV4, SpeechModelV4, TranscriptionModelV4, RerankingModelV4, or Experimental_VideoModelV4.

Before introducing a dependency, public API pattern, or new abstraction, read contributing/decisions/README.md and relevant accepted ADRs. Prefer existing provider utilities and implementation patterns.

Scaffold the Package

Create packages/<provider>/ by adapting a current, comparable provider package. A typical package contains:

packages/<provider>/
├── src/
│   ├── index.ts
│   ├── version.ts
│   ├── <provider>-provider.ts
│   ├── <provider>-provider.test.ts
│   ├── <provider>-<model-type>-model.ts
│   ├── <provider>-<model-type>-model.test.ts
│   └── <provider>-<model-type>-options.ts
├── CHANGELOG.md
├── README.md
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsup.config.ts
├── turbo.json
├── vitest.node.config.js
└── vitest.edge.config.js

Preserve current package conventions rather than recreating configuration from memory:

  • Set the repository package version to exactly 2.0.0, with no prerelease suffix.
  • Create CHANGELOG.md with an initial # @ai-sdk/<provider> heading.
  • Use ESM output and the current tsup package-version injection pattern.
  • Extend ./node_modules/@vercel/ai-tsconfig/ts-library.json, enable a composite project, and add package references for workspace dependencies.
  • Include the standard build, clean, type-check, Node test, and Edge test scripts.
  • Include the standard files, documentation prepack, repository, bugs, engines, and public provenance publishing metadata.
  • Use workspace:* for AI SDK workspace dependencies. Add @ai-sdk/test-server only when tests use it.
  • Support the repository's Zod 3 and Zod 4 peer dependency range and use zod/v4 for new implementation schemas.

Run pnpm update-references after adding or changing workspace dependencies.

Implement the Provider Factory

Follow the current provider factory pattern:

  • Define a provider interface that extends ProviderV4.
  • Export create<Provider>(settings) and a default provider instance.
  • Make the provider callable when it has a meaningful default model type and comparable providers follow that pattern; otherwise return a provider object.
  • Set provider.specificationVersion = 'v4'.
  • Implement the fully specified factory methods required by ProviderV4, such as languageModel, embeddingModel, and imageModel.
  • Add short aliases such as chat, embedding, or image only when they improve the provider's API.
  • Throw NoSuchModelError from unsupported required model factories.
  • Support provider-appropriate settings such as apiKey, baseURL, headers, and a custom fetch implementation.
  • Load credentials with loadApiKey or the appropriate shared utility, normalize configurable base URLs, and include the package version in the user-agent suffix.
  • Export the provider factory, default instance, public option types, model ID types, and VERSION from src/index.ts.

Implement Model Classes

Implement each supported model using the appropriate interface from @ai-sdk/provider and shared utilities from @ai-sdk/provider-utils.

Provider option types and schemas must follow the repository naming and export rules. User-facing option fields should use .optional() unless null is meaningful. Response schemas should be minimal, tolerate unused provider fields, and use .nullish() where the API may omit or return null.

All model classes must implement the workflow serialization contract described in Provider development notes:

  • make model configuration headers optional
  • add WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE static methods
  • use serializeModel, serializeModelOptions, or the matching existing pattern
  • ensure authentication and other non-serializable functions can be restored from request options or the workflow environment

Handle Responses, Errors, and URLs Safely

  • Never use JSON.parse in production code. Use parseJSON or safeParseJSON from @ai-sdk/provider-utils.
  • Validate successful and failed responses with minimal schemas and shared response handlers such as createJsonResponseHandler and createJsonErrorResponseHandler.
  • Introduce a custom AISDKError subclass only when the package needs a new public SDK error type; ordinary provider HTTP failures should use the shared API error handling.
  • Set validateUrl explicitly on every getFromApi call.
  • Use validateUrl: true when the URL host or scheme comes from a provider response, and false when it is derived from a developer-configured base URL.
  • Use trustedOrigin for legitimate response URLs that may point to a configured private or self-hosted endpoint.
  • Use credentialedOrigin when credentials may be sent on the first hop, so they are withheld from off-origin URLs and redirects.

Read Secure URL handling before implementing any polling or provider-supplied download URL flow.

Test Against the Real Contract

Add focused tests for:

  • provider defaults, custom settings, factory aliases, and unsupported model types
  • request serialization and response parsing
  • streaming events, usage, finish reasons, warnings, tool calls, and provider metadata where supported
  • error response parsing and malformed responses
  • workflow serialization and deserialization
  • URL trust decisions for polling or downloads
  • both Node.js and Edge runtimes

Use real provider responses as fixtures when practical. Read the capture API response fixture skill before capturing them. Trim oversized fixtures only when doing so does not change their semantics.

Add Examples and Repository Integration

Read the AI Functions example skill before adding examples.

For each supported model type, put the entry example at:

examples/ai-functions/src/<function>/<provider>/basic.ts

Put additional examples in the same provider directory with descriptive kebab-case.ts names. Do not create flat provider files such as src/generate-text/<provider>.ts.

Also update the relevant repository integration points:

  • add @ai-sdk/<provider> to examples/ai-functions/package.json
  • add its project reference to examples/ai-functions/tsconfig.json
  • add required credentials to examples/ai-functions/.env.example
  • add credential names to the root turbo.json environment configuration when needed
  • run pnpm update-references to update root and package TypeScript references

Run representative examples against the real API and confirm both non-streaming and streaming behavior when supported.

Add Package and Provider Documentation

  • Write the package README.md with installation, authentication, configuration, supported models, and basic usage.
  • Add content/providers/01-ai-sdk-providers/<last number + 10>-<provider>.mdx with setup, model capabilities, provider options, and examples.
  • Configure the package's documentation prepack script to include that provider page.

Prepare the Release

Create a major changeset for the new provider package. The repository package remains at plain 2.0.0; do not add -beta, -canary, or another prerelease suffix.

Before the first automated release, coordinate with the Vercel IT team to bootstrap an empty @ai-sdk/<provider> package on npm at 0.0.0 and configure its Trusted Publisher. Follow Bootstrapping a new @ai-sdk/* package. The temporary npm bootstrap version is separate from the repository package version.

When main is in prerelease mode, do not backport the new package to a stable vX.Y branch.

Verify the Complete Change

Run, at minimum:

pnpm --filter @ai-sdk/<provider> build
pnpm --filter @ai-sdk/<provider> test
pnpm --filter @ai-sdk/<provider> type-check
pnpm type-check:full
pnpm check

Also run the new examples with the required provider credentials. Run the root build when changes to shared packages or build configuration make it relevant.

Completion Checklist

  • [ ] First-party package approved in an issue
  • [ ] Official OpenAPI specification reviewed, or its absence documented
  • [ ] API specification checked against documentation and real responses
  • [ ] Comparable current provider implementation selected
  • [ ] Repository package created at version 2.0.0
  • [ ] Package, TypeScript, build, test, provenance, and documentation configuration added
  • [ ] Provider factory implements ProviderV4
  • [ ] Supported model classes and public option types implemented
  • [ ] Workflow serialization implemented for every model class
  • [ ] Response parsing, error handling, and URL fetching follow repository security rules
  • [ ] Node and Edge tests pass with representative response fixtures
  • [ ] Nested AI Functions examples added and run successfully
  • [ ] Example dependencies, TypeScript references, environment variables, and Turbo configuration updated
  • [ ] README and provider

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars26.9k
CategorySecurity
Updated1mo ago
Forks5.2k

Languages

TypeScript

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium