fix(setup-changesets): pair the CLI and action majors, add the v2→v3 upgrade path

[unional]

Fixes #7.

Summary

The skill taught changesets/action@v1 with the v1 input names, @changesets/config@3.0.0, and an unpinned @changesets/cli init — which now installs v3. Following it today produces a v3 CLI wired to a v1 action, which fails on the first release:

Error: This version of the Changesets action is designed to work with Changesets CLI v3.
Changesets CLI v2 is not supported; use Changesets action v1 instead, which is compatible with CLI v2.

There was also no upgrade path: Step 1's .changeset/ already exists exit sends you to "audit config/scripts/CI only", which does not surface a major mismatch.

Found and validated while unbreaking cyberuni/universal-plugin — its release job had been red since the shared workflow moved to changesets/action@v2.1.0 (cyberuni/universal-plugin#35). 30 repos call that workflow; 25 were on CLI v2 when it landed.

Changes

SKILL.md:

• New § The CLI and the action must match majors at the head of Step 5 — the error text plus a pairing table. Written as a relationship (CLI major ↔ action major ↔ input names) rather than a frozen version number, so it stays true across future patches.
• Both action snippets → @v2 with the renamed inputs (version-script, publish-script, github-token input rather than the GITHUB_TOKEN env var). Called out that the old names are silently ignored under v2, so a half-done bump leaves the action running with no publish script.
• Step 1 detects the CLI major and the action major, and gains an early exit routing a mismatch to the new upgrade reference.
• Step 3 config schema → @changesets/config@4.0.0. Step 2 pins @changesets/cli@3.
• Option B gains a note that a shared workflow makes the action version a fleet-wide decision — the failure surfaces in consumer repos, on their next push to main, not at merge time.
• Step 7 asserts the pairing before anything else, and adds changeset status to prove pending changesets survive an upgrade.
• Token note corrected — under v2 the PAT goes to the github-token: input, not GITHUB_TOKEN: env.

references/migration/cli-v3-upgrade.md (new) — follows the existing reference-loading discipline, read only when Step 1 detects a mismatch:

• version floors (Node ^22.11 || ^24 || >=26, npm >=10.9.0, pnpm >=10.0.0, yarn >=4.5.2, Yarn Classic dropped)
• the full v3 breaking-change table (prettier → format, privatePackages now opt-in, changeset tag → git-tag, --sinceMaster removed, version exits 1 with no changesets, prerelease dir move, peer bumps now patch, ESM)
• the note that most repos need no config migration beyond the schema URL
• a prove-it procedure that runs changeset version for real and reverts it

Test plan

• Diffed against main — the patch is additive on current upstream text; no restructuring, and the references/ci + references/migration architecture is untouched
• Procedure validated end to end on a real repair: changeset status under v3 parsed all 10 pending changesets, pnpm run version produced the correct minor and changelog, repo verify green
• Every changesets/action@v1 reference converted except the two intentional ones in the pairing table
• No files outside skills/setup-changesets/ modified

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: b542358

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR