Agent skill · software engineering · jeremylongshore
clerk-upgrade-migration
Manage Clerk SDK version upgrades and handle breaking changes.
Why this skill is useful
Adds executable scripts for upgrading Clerk SDK versions and handling breaking changes that aren't in public documentation.
What it needs
Requires npm installed locally. About 4k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Clerk Upgrade & Migration Current State !npm list @clerk/nextjs @clerk/clerk-react @clerk/express 2>/dev/null grep clerk echo 'No Clerk packages found' Overview Safely upgrade Clerk SDK versions and handle breaking changes. Covers version checking, upgrade procedures, common migration patterns, and rollback planning. Prerequisites Current Clerk integration working Git repository with clean working state Test environment available for validation Instructions Step 1: Check Current Version and Available Updates Step 2: Review Breaking Changes Key version milestones to watch for: v5 to v6: auth() became async (must await auth()) v5 to v6: authMiddleware renamed to clerkMiddleware v5 to v6: Import paths changed to @clerk/nextjs/server Step 3: Upgrade Process Step 4: Handle Common Migration Patterns v5 to v6: auth() is now async Find all affected files: v5 to v6: Middleware migration v5 to v6: Import path changes Fix import paths across codebase: Step 5: Update Type Definitions Step 6: Test Upgrade Step 7: Rollback Plan Output Clerk SDK upgraded to latest version Breaking changes migrated (async auth, new middleware, import paths) Type definitions updated All tests passing Rollback procedure documented Error Handling Error Cause Solution ------- ------- ---------- Type errors after upgrade API signature changes Add await to auth(), update imports authMiddleware is not exported Renamed in v6 Use clerkMiddleware from @clerk/nextjs/server auth() returns Promise Now async in v6 Add await to all auth() calls Import not found Path changed Use @clerk/nextjs/server for server-side imports Version mismatch Clerk packages on different versions Update all @clerk/ packages together Examples Automated Migration Script Resources Clerk Changelog Clerk Upgrade Guides GitHub Releases Next Steps After upgrade, review clerk-ci-integration for CI/CD updates.
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/clerk-upgrade-migration