vercel/major-version-mode

Context

This task is part of the next AI SDK major release. Breaking changes are acceptable.

Breaking Change Guidelines

While breaking changes are acceptable, it is still encouraged to minimize unnecessary disruption for 3P consumers of the AI SDK. Providing deprecated aliases and automated migration logic can help ease the transition.

Renamed/changed exports

If renaming or modifying an exported function or type, provide a deprecated alias as a package-level export where feasible:

/** @deprecated Use `newFunctionName` instead. */
export { newFunctionName as oldFunctionName } from './new-module';

Only do this if it doesn't introduce meaningful technical debt. If it does, skip the alias — but check with the user first before making a clean break.

Modified message types (e.g. in `@ai-sdk/provider-utils`)

If modifying model message shapes (e.g. content part types in packages/provider-utils/src/types/content-part.ts):

Deprecate in @ai-sdk/provider-utils rather than removing immediately, if feasible. Mark deprecated types/members with a @deprecated JSDoc comment and a TODO note to remove in the following major version.
Keep deprecated equivalents in packages/ai/src/prompt/content-part.ts — this file is the consumer-facing layer and should retain the old shapes in the Zod schemas so existing consumer code continues to compile with a deprecation warning. Include a similar note about deprecation and removal in the following major version.
If clean deprecation isn't feasible without meaningful technical debt, a hard removal may be preferred — but check with the user first.

Provider spec changes (`@ai-sdk/provider`)

The provider package defines the spec that provider implementers code against. It should generally not be modified outside of major versions, so keeping the spec clean and consistent is critical.

Breaking changes without maintaining temporary backward compatibility measures are more acceptable here than elsewhere, because the audience is smaller — far fewer developers implement their own providers than build features on top of the AI SDK.

Rules:

Only modify the latest spec version. Older versioned spec interfaces must remain completely untouched.
Deprecated aliases are not required — a clean break is preferred to preserve spec clarity.
The current spec version is not the same as the current AI SDK major version number. If it's unclear which spec version to operate on, ask the user before proceeding.

Documentation

After implementing changes, update relevant documentation in content/docs/.

If the change requires consumers to update their code or migrate stored data, add a section to the latest migration guide:

Find the migration guide with the highest version number in content/docs/08-migration-guides/
Add a concise section explaining what changed and how to migrate

Files1

1 files · 552 B

Select a file to preview

Overall Score

78/100

Grade

B

Good

Safety

92

Quality

76

Clarity

82

Completeness

65

Summary

This is a contextual skill for working on the next major version of the AI SDK. It provides guidelines for managing breaking changes, including strategies for deprecation, backward compatibility measures, and when to make clean breaks. The skill is explicitly marked as internal and must be invoked by the user (e.g., '/major-version-mode') rather than triggered autonomously.

Detected Capabilities

Provide breaking change guidelines and decision frameworkGenerate deprecation patterns (JSDoc comments, deprecated aliases)Identify which files need updates (content-part.ts, provider specs)Guide documentation updates to migration guidesDetermine when to skip deprecation and make clean breaksManage spec versioning and backward compatibility

Trigger Keywords

Phrases that MCP clients use to match this skill to user intent.

major version releasebreaking changesdeprecate exportsmigration guideprovider spec updatebackward compatibility

Referenced Domains

External domains referenced in skill content, detected by static analysis.

www.apache.org

Use Cases

Plan and implement breaking changes for a major SDK release
Decide when to deprecate exports versus remove them outright
Update message types and provider specs while managing consumer impact
Add migration guidance and deprecation aliases for API changes
Coordinate breaking changes across multiple packages (@ai-sdk/provider-utils, @ai-sdk/provider, etc.)

Quality Notes

✓ Clear scope: applies only to major version releases and must be explicitly invoked
✓ Well-structured decision trees for deprecation vs. removal
✓ Specific file paths and package names referenced (provider-utils, provider, ai packages)
✓ Practical code examples (deprecation alias pattern) aid implementation
✓ Balances consumer impact with API cleanliness — shows nuanced thinking
✓ Acknowledges different audiences (consumers vs. provider implementers) and adjusts guidance accordingly
⚠ No explicit error handling or edge cases documented (e.g., what if a deprecated alias introduces circular imports?)
⚠ Mentions 'check with the user first' multiple times but doesn't specify exact prompts or decision criteria — relies on agent judgment
⚠ Documentation update instruction is brief — 'update relevant documentation' is somewhat vague without examples of what 'relevant' means
⚠ No discussion of testing strategy for deprecation patterns or migration validation

Model: claude-haiku-4-5-20251001Analyzed: May 2, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

major-version-mode