[njb90]

Summary

Most people install skills once and never update them. With this change, each skill checks whether it's up to date the first time it's used in a conversation, and tells the user when a newer version is available.

How it works

Each SKILL.md gets a short "Before you start: check this skill is current" section directly under its H1. The first time the skill is used in a conversation, the agent:

1. Fetches the Cloudinary skills index at https://cloudinary.com/documentation/.well-known/agent-skills/index.json. This is the Agent Skills discovery index, which the skills CLI can also install from.
2. Compares the published x-cloudinary-version for the skill with the installed version.
3. If the published version is newer, tells the user in one line that they can update with npx skills update <name>, or reinstall with npx skills add https://cloudinary.com/documentation. Otherwise it carries on.

Things it doesn't do:

• Run the update itself.
• Repeat the check within the same conversation.
• Retry if the fetch fails.
• Suggest a downgrade when the installed skill is newer than the index.

Agents that can't fetch URLs skip the check. The check also follows the user's or project's instructions to skip it.

What's sent

The request includes the skill name and version, the agent product and model, the kind of task (for example setup or docs), and the user's cloud name, but only if the agent already has it from the conversation or the code it's working on. The block tells the agent never to open .env files or read CLOUDINARY_URL for this, and never to include API keys or secrets. The README documents this and how to turn the check off.

Keeping the block consistent

• templates/version-check.md is the single source for the block.
• scripts/check-version-block.sh --fix renders it into every skill, filling in the skill's name, version, and referrer.
• A new CI job, version-check-block, fails if a skill's block is missing, edited by hand, misplaced, or out of date after a version bump.
• CONTRIBUTING explains how to change the block.

Versions

Skill	Before	After
cloudinary-docs	1.1.0	1.2.0
cloudinary-transformations	1.0.4	1.1.0
cloudinary-react	1.0.2	1.1.0
cloudinary-next	1.0.0	1.1.0

Testing

Headless Claude Code runs, with the skills installed from this branch:

Scenario	Result
Skill current (next, docs)	One check each. The agent didn't mention it.
Skill out of date (react installed as 0.9.0)	One check, with a correct one-line update notice
Cloud name stated in the prompt (next)	One check, cloud name included
Cloud name in project code (react)	One check, cloud name included
No cloud name available	One check, cloud name left out

To test locally:

npx skills add cloudinary-devs/skills#feat/version-check

Then ask your agent a Cloudinary task. To see the update notice, change the version in an installed skill's SKILL.md to 0.9.0 (in both the frontmatter and the block) and start a new conversation.