Versioning a Claude skill so people know what changed
A skill changes behaviour for everyone who uses it, so changes need a version and a note. A simple scheme, where to record it, and when a change is breaking.
A change to a skill changes behaviour for everyone who has it. Without a version, the only way to know what changed is to diff folders, which nobody does.
A simple scheme
| Bump | When |
|---|---|
| Major | Output changes in a way users relied on, or it stops triggering for common requests |
| Minor | New rules, new references, better coverage, nothing removed |
| Patch | Wording fixes, typo fixes, clarified examples |
Write the changelog for the user
## 1.2.0, 25 Sept 2026
- Added: leaderboard recipe.
- Changed: accent now allowed twice per screen, was once.
- Checked against: trigger set, 20 prompts.The last line matters: say what you tested. When a Claude update forces a change, note that too, as described in regression testing after a Claude update.
Questions
Does a Claude skill need a version number?
Once anyone else uses it, yes. A version and a changelog tell people what changed and let them report problems against a specific release.
What counts as a breaking change in a skill?
Anything that changes what it produces in a way users relied on: a renamed token, a removed rule, a description change that stops it triggering for a common request.
Where should the version live?
In the README and at the top of a changelog in the skill folder. If you distribute through a plugin, in its manifest too.