skills.rest
vercel
vercelOFFICIAL
Explore all skills by this author →
Website𝕏@vercelGitHub

major-version-mode

Guides breaking changes for the next AI SDK major release with deprecation and migration rules.

26.5k|5.1k|Updated May 23, 2023
Search Tags:#deprecation#migration guide#ai sdk#typeScript#Breaking Changes#provider spec#major release
One-click install
npx skills add https://github.com/vercel/ai --skill major-version-mode
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: major-version-mode
Source: https://github.com/vercel/ai/tree/main/skills/major-version-mode
Command: npx skills add https://github.com/vercel/ai --skill major-version-mode

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When working on the next AI SDK major release, engineers need consistent rules for introducing breaking changes without unnecessarily disrupting third-party consumers. This Skill supplies the context and guardrails for renaming exports, modifying message types, and changing the provider spec.

Core Features & Use Cases

  • Deprecation Guidance: Provides patterns for adding deprecated aliases when renaming or modifying exported functions and types.
  • Message Type Change Rules: Defines how to deprecate content part types in @ai-sdk/provider-utils while keeping consumer-facing Zod schemas in packages/ai backward compatible.
  • Provider Spec Governance: Enforces that only the latest provider spec version is modified, with clean breaks preferred over aliases.
  • Use Case: While renaming an exported function for the next major release, the Skill instructs you to add a deprecated alias export and update the latest migration guide in content/docs/08-migration-guides/.

Quick Start

Invoke /major-version-mode before starting work on a breaking change for the next AI SDK major release.

Frequently Asked Questions about major-version-mode

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I rename an exported function in the AI SDK without breaking consumers?▼

Add a deprecated alias as a package-level export that re-exports the new function under the old name with a @deprecated JSDoc comment. Skip the alias only if it introduces meaningful technical debt, and check with the user before making a clean break.

How do I modify message content part types in @ai-sdk/provider-utils?▼

Deprecate the old types with @deprecated JSDoc comments and a TODO to remove them in the following major version. Keep the old shapes in the consumer-facing Zod schemas in packages/ai/src/prompt/content-part.ts so existing code still compiles.

Can I modify older versions of the AI SDK provider spec?▼

No, only the latest spec version may be modified; older versioned spec interfaces must remain completely untouched. The spec version is not the same as the AI SDK major version number, so ask the user if it is unclear which spec to change.

When should I use major-version-mode in the AI SDK repository?▼

Use it only when explicitly invoked, such as via /major-version-mode, while working on the next AI SDK major release. It should not trigger automatically based on task content, since breaking changes are only acceptable in that context.

What documentation updates are required after a breaking change in the AI SDK?▼

Update relevant documentation in content/docs/ and, if consumers must change code or migrate stored data, add a concise section to the highest-numbered migration guide in content/docs/08-migration-guides/ explaining what changed and how to migrate.

Related Skills

Explore More Software Engineering Skills→
tim-o-privatetim-o-private

update

Update assistant-ui and AI SDK packages to latest versions with migration guidance.

Official
Intermediate
masermediagroup-stackmasermediagroup-stack
1

next-upgrade

Upgrade Next.js projects across major versions using official guides and codemods.

Community
Advanced
ZurybrZurybr

build-cython-ext

Fix Cython extension builds for modern Python and NumPy versions.

Community
Intermediate
jim60105jim60105
21

update-github-actions-version

Update major GitHub Actions versions in workflow files and flag breaking changes.

Community
Intermediate