[PaulBoye-py]

Summary

Updates the cloudinary-next skill for next-cloudinary v7, while keeping projects on v6 supported. The skill now checks which next-cloudinary and Next.js versions a project uses before writing code, follows v7 by default, and switches to v6 guidance when the project is on v6.

next-cloudinary 7.0.0 is now on npm's latest tag, so a plain npm install next-cloudinary installs v7.

Why

next-cloudinary v7 requires Next.js 16, React 18.2 or 19, and Node.js 22, and changes a few things agents generate code for ('use client' is built in, onUpload is removed, an exports map is added, Video Player v4). The same skill has to serve both v6 and v7 projects.

While testing, two existing problems turned up that affect both versions:

• The App Router OG image example reads params.slug directly. On Next.js 16 params is a Promise, so the image was generated with empty text, without any build error.
• The recommended useRef<unknown>(null) for playerRef doesn't type-check when passed to CldVideoPlayer.

The skill also said CldImage works in Server Components. That is only true in v7: in v6, rendering it from a Server Component fails with useState is not a function.

Changes

• SKILL.md: a version check as the first workflow step; the 'use client' rules rewritten (v7: components can render in Server Components unless functions are passed; v6: every component needs a Client Component); onUpload marked as removed in v7; the two new references added to the map. Version bumped to 1.1.0.
• New references/v6.md: requirements and the short list of v6 differences (Server Components, CSS path, video player version, onUpload, seed, deep imports, params on Next.js 14).
• New references/migrating-to-v7.md: when a project can upgrade (and when it should stay on v6), what the upgrade gives, what to search for and change, and the steps.
• Install rule (project-setup.md, checklist): the major version is picked from the project's Next.js version (next-cloudinary@6 on Next.js 15 or earlier). An existing project keeps its major version unless the user wants to upgrade.
• Video player (video-player.md): Video Player v4 notes (Studio posters, custom CSS, the 7.0 aspectRatio poster limitation and its workaround), the CSS paths for each version, typed refs, and onDataLoad.
• OG images: await params for Next.js 15 and 16. The default size is corrected to 1200×627 (the skill said 1200×630; v6 and v7 both generate 1200×627).
• TypeScript: playerRef typed with the CloudinaryVideoPlayer type exported by next-cloudinary.
• Troubleshooting: new entries for the ERESOLVE install error, "Functions cannot be passed directly to Client Components", the v6 useState error, the short CSS path on v6, ERR_PACKAGE_PATH_NOT_EXPORTED, the aspectRatio poster, Studio posters and the v6 remount issue. Outdated entries updated.
• Smaller updates: fillBackground seed and the allowed assetType values, the decision tree, and the import rules.

Testing

Every behaviour the skill describes was checked against the published packages, each in a separate Next.js build. The Server Component, CSS path, deep import and playerRef checks were run on 6.19.3 and 7.0.0. The other checks were run on 7.0.0-beta.17, whose published code is identical to 7.0.0 apart from the version number.

• Server Component rendering of each component, with and without functions or Server Actions, on v6 and v7
• the short and long CSS paths, deep imports, the playerRef type, and the colors / fontFace / logo props with Video Player v4
• the corrected OG example on Next.js 15 and 16

The updated skill was then installed in six test projects, and Claude Code was given the same tasks in each (a video page with a play event, an OG image page, an upload page). Each project was then built and checked in a browser:

Project	Result
Next.js 15 + v6	Stayed on v6; explained that v7 needs Next.js 16 first
Next.js 16 + v6	Stayed on v6; suggested the upgrade once
Next.js 16 + v7	Followed v7 guidance; no upgrade prompt
New project on Next.js 15	Installed next-cloudinary@6 and explained why
Next.js 16 + v6, asked to upgrade	Fixed onUpload, a deep import and analytics: false; flagged aspectRatio and the custom player CSS
New project on Next.js 16	Installed next-cloudinary 7.0.0 and followed v7 guidance

The first five runs were done before the 7.0.0 release, so the v7 projects used 7.0.0-beta.17. The last run used 7.0.0.

In all six, npm run build passed, the OG image URL contained the slug as a text overlay, "playing" was logged on playback, and the upload widget opened. All six runs used Claude Code. The skill wasn't tested with other AI coding agents.

Repo checks: check-discovery.sh, check-links.sh and check-versions.sh pass.

Related PRs

• Check that each skill is up to date on first use #26 also edits SKILL.md. It merges cleanly with this branch.
• Feat: Add cloudinary-upload skill #21 is based on an older main. Its cloudinary-next files are the same as on current main, so it doesn't overlap with these changes.

Follow-ups

• create-cloudinary-next bundles a copy of this skill as a fallback. It should be refreshed after this merges.
• The aspectRatio poster limitation is planned to be fixed in next-cloudinary 7.1. The skill text will need updating then.

[PaulBoye-py]

Hi @strausr, just a note on the failing "Every SKILL.md is discovered" check.

It isn't related to the changes here. The check runs npx skills@latest, which now requires Node 22.20 or later, but the workflow on main still uses Node 20, so the CLI exits before it finds any skills (all four are reported as missing, including ones this PR doesn't touch). #26 already updates the workflow to Node 22. Once that's merged, I'll update this branch so the check runs again. Locally, on Node 24, all four skills are discovered. Thank you!

[PaulBoye-py]

Thanks for the review, @strausr!

I've applied all four suggestions in the latest commit. Would you mind taking another look when you have a moment?

[strausr]

@PaulBoye-py Looks great!