Add the cloudinary-video skill by konforti · Pull Request #23 · cloudinary-devs/skills

konforti · 2026-09-14T14:39:31Z

Adds cloudinary-video to the collection as a platform skill, alongside cloudinary-docs and cloudinary-transformations.

What it covers

Building video experiences on the Cloudinary Video Player: choosing adaptive or progressive delivery per source, configuring the player and its saved settings, captions, chapters, transcripts, hotspots, and AI analysis. It covers the video-specific decisions that cloudinary-transformations and cloudinary-docs leave open, and points to them for everything else.

Layout follows the existing skills: SKILL.md (When to Use, Quick Start rules, Additional Resources, Related Skills) plus a references/ directory it links into. Version 1.0.0; doc links carry install_source and referrer=video-skill.

Changes from the first version

Based on the review comments on this PR and the Oct 7 skills-pack discussion:

Moved to skills/platform/cloudinary-video/ and listed under Platform in the README.
Migration split out. Getting originals off Brightcove, Vimeo, YouTube, and Wistia now lives in a draft asset-migration use-case skill (Add a draft asset-migration skill #25). Two short tips remain here.
Quick Start rules near the top, led by "deliver video through the Cloudinary Video Player".
player.md trimmed to the traps, with a link to the API reference for every option.
Fact-checked line by line against the docs, the player 4.1.0 source, and live requests on the demo cloud, which corrected several claims:
- first-request behaviour (the first viewer gets a streaming file with the wrong duration; 423 only for async derivations);
- switching one player between progressive and ABR (the breakpoint resize sticks, so use separate players, or reset with player.transformation({}); verified in a browser);
- maxDpr, preload, lazy, autoplayMode, eager with f_auto and with Optimize by default, translated captions, and audio-description tracks;
- duration thresholds aligned with Cloudinary's field guidance.
New guidance for audio-only sources, lazy posters, and seek thumbnails on loops.
Tested end to end by three agents building different pages from the skill alone, each verified in a browser.
No internal references; the CSM guide is no longer named.

The claim tests

The tests moved out of the skill directory to tests/cloudinary-video/, so they no longer ship to users who install the skill (noted in CONTRIBUTING.md). They assert the skill's load-bearing claims against live endpoints, now on Cloudinary's public demo cloud:

./tests/cloudinary-video/skill-claims.sh          # no credentials needed

21 checks pass; the chapters and translated-transcript paths are skipped unless FEATURE_CLOUD and FEATURE_ID point at a cloud that has them. --cloud provisions a fresh cloud to assert the upload and add-on claims, using any JPEG and speech MP4 set in TEST_IMAGE and TEST_VIDEO.

Useful links

JIRA Ticket
Migration skill: Add a draft asset-migration skill #25

Provenance

Developed by @konforti in CloudinaryLtd/cloudinary-video-skill, where the demo site it was built and validated against also lives. Revised by @ed-cld for the review above.

🤖 Generated with Claude Code

Covers building video experiences on the Cloudinary Video Player — adaptive streaming, chapters, captions, transcripts, hotspots and AI analysis — plus migrating media in from Brightcove, Vimeo, YouTube and Wistia. The skill ships with the claim tests it was built against. They assert the load-bearing factual claims (transformation behaviour, async output shapes, player distribution, source-platform limits) against live endpoints, so a claim going stale fails loudly rather than misleading an agent. The default mode needs no credentials; --cloud additionally provisions a cloud and needs media fixtures via MEDIA_DIR, which are too large to vendor here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…tion - Move the skill to skills/platform/cloudinary-video and list it under Platform in the README. - Split out the platform-migration content (getting originals off other platforms, mining an existing site, source-platforms.md) for a separate asset-migration skill; keep two short tips for media from other platforms. - Follow the repo conventions: version 1.0.0, a "Reference for... Use when..." description, When to Use, Quick Start rules, Additional Resources with tracked doc links, and Related Skills. Move upload and preparation detail to references/upload-and-prepare.md to keep SKILL.md under 500 lines. - Correct claims that the docs, the player 4.1.0 source, or live requests contradict: first-request behaviour (streams with the wrong duration; 423 only for async derivations), sourceTypes and breakpoints per source() call, maxDpr, autoplayMode, eager with f_auto, thresholds aligned with the field guidance, audio-only sources, lazy posters, seek thumbnails on loops, and warming with a browser User-Agent. - Trim player.md to traps and link the API reference, drop internal references, and replace em dashes. - Move the claim tests to tests/cloudinary-video, run them against the public demo cloud, and note the tests/ convention in CONTRIBUTING.md.

- Switching one player between progressive and ABR: the breakpoint resize stays in the player's transformation, so breakpoints: false alone still returns 400. Recommend separate players, and give the reset that works (player.transformation({}) plus breakpoints: false), verified in a browser. - Player facts from the 4.1.0 source: preload defaults to metadata, lazy resolves to a placeholder until loadPlayer(), controls() is a wrapper method, which bundles construct synchronously, and colors.text must contrast with colors.base. - Captions and tracks: translations need only a language, audio description goes in a descriptions track, and Studio transcripts can be uploaded only for translations. - Delivery: use f_auto:video in the native fallback (matching cloudinary-transformations), the combined f_auto,q_auto can encode differently, e_preview fails on very short sources, eager isn't supported with Optimize by default, and auto_video_details isn't supported by the SDKs or the MCP. - Remove undocumented internal endpoints, the unverified quota numbers, the "how much is verified" section, and demo-specific wording; reconcile the React guidance with cloudinary-react; make Phase headings H2. - Make the warming loop stop on real errors and report a timeout, and test that both f_auto forms are accepted rather than byte-identical.

- controls defaults to false in player 4.1.0, so a click-to-watch player shows no play button or control bar. Say to set controls: true (or the controls attribute) in SKILL.md B3 and player.md. - A type="video/mp4" hint on an f_auto:video source is fine: Chrome plays the WebM it is served. Remove the warning from the native <video> fallback. - Say "different players" for the ABR plus progressive page shape.

- Add the transcription entry points for existing assets (explicit method, Video Player Studio, the player, MediaFlows), the named progressive and ABR use cases, the "how will you measure impact" discovery question, and that generated transcripts can be edited in Studio before viewers see them. - Say which mobile players send analytics by default (iOS and Android), and describe mobile breakpoints only as undocumented. - Note that Optimize by default is enabled through support and is ignored when a URL has a format parameter or named transformation, and that q_auto supports H.264, H.265, and VP9 only.

konforti

LGTM - approved! (GitHub won't let me approve my own PR :))

konforti and others added 2 commits September 14, 2026 17:39

Merge branch 'main' into add-cloudinary-video-skill

66bf0a3