Major Version Mode
Switch your coding agent into maintainer mode for the next Vercel AI SDK major release when you are intentionally shipping breaking API changes.
Overview
Major-version-mode is an agent skill for the Build phase that puts your session in next AI SDK major-release context with breaking-change and deprecation guidelines.
Install
npx skills add https://github.com/vercel-labs/ai --skill major-version-modeWhat is this skill?
- Explicit invocation only via /major-version-mode—never auto-triggers from task text
- Breaking-change playbook: deprecated export aliases and optional automated migrations
- Renamed exports pattern with @deprecated JSDoc re-exports at package level
- Provider message type changes: deprecate in @ai-sdk/provider-utils before hard removal
- Requires user confirmation before clean breaks that skip compatibility aliases
Adoption & trust: 5 installs on skills.sh; 24.7k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are editing AI SDK packages for a major bump but the agent keeps proposing backward-compatible patches that dodge necessary API breaks.
Who is it for?
Maintainers or advanced contributors actively working on the Vercel AI SDK major release branch with explicit user invocation.
Skip if: App developers integrating the stable AI SDK in production apps, or any task where the user did not invoke /major-version-mode.
When should I use this skill?
User explicitly invokes via '/major-version-mode'; do NOT trigger autonomously from task content.
What do I get? / Deliverables
The agent treats breaking changes as acceptable, applies alias and deprecation patterns from the skill, and checks with you before irreversible export removals.
- Breaking-change refactors with optional deprecated re-exports
- JSDoc-deprecation notes on transitional types
Recommended Skills
Journey fit
Major-version work is core library integration work done while building or refactoring the AI SDK packages consumers depend on. The skill governs provider-utils message shapes, package exports, and migration aliases—classic agent-to-SDK integration surface area.
How it compares
Use for SDK semver-major maintenance context—not for everyday app integration or generic refactor skills.
Common Questions / FAQ
Who is major-version-mode for?
It is for people changing @ai-sdk packages during a planned major release—library maintainers and serious contributors—not casual API consumers.
When should I use major-version-mode?
Only when you explicitly invoke /major-version-mode at the start of a breaking-change session on AI SDK internals; it must not run autonomously from normal coding tasks.
Is major-version-mode safe to install?
Review the Security Audits panel on this Prism page before installing; the skill steers large API-breaking edits so human review of diffs is essential.
SKILL.md
READMESKILL.md - 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: ```typescript /** @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`): 1. **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. 2. **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. 3. 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