semver
Skill0 starsChanged 42 days agoMITView on GitHub
Use when about to change a version number (package.json, pyproject.toml, Cargo.toml, MARKETING_VERSION, CFBundleShortVersionString, a VERSION file), create or push a release tag, cut or publish a release, or when the user says ship, release, publish or cut a version, or asks which version comes next.
8 other projects use a version of this.
Adopted by
Most recently taken up by
- 27Aaron/skillstheir own version, first seen Nov 8, 2026
- r3b1s/skillstheir own version, first seen Nov 8, 2026
- mqmalagris/agent-skillstheir own version, first seen Nov 5, 2026
- lelborn/skillstheir own version, first seen Nov 1, 2026
- DeepSpaceCartel/skillstheir own version, first seen Oct 25, 2026
- jasoncrawford/claude-skillstheir own version, first seen Apr 25, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- kayaman/skills★ 3same name
- 27Aaron/skills★ 2same name
- DeepSpaceCartel/skills★ 2same name
- r3b1s/skills★ 2same name
- jasoncrawford/claude-skills★ 1same name
- kayaman/agentskills★ 1same name
- lelborn/skills★ 0same name
- mqmalagris/agent-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository34 other files it gives its agents.
- afkSkill
- apple-contactsSkill
- apple-devSkill
- apple-notesSkill
- apple-photosSkill
- bug-huntSkill
- catch-upSkill
- cherriSkill
- chrome-controlSkill
- claude-sessionsSkill
- coordinatorSkill
- discountsSkill
- forge-skillSkill
- groupmeSkill
- herdr-crewSkill
- iconsSkill
- imsgSkill
- language-selectionSkill
- laterSkill
- mac-controlSkill
- nix-mechanicsSkill
- notion-cliSkill
- posthogSkill
- quotaSkill
- redditSkill
- rustSkill
- scoutSkill
- social-contentSkill
- spotifySkill
- travelSkill
- validate-ideaSkill
- verdictSkill
- web-reconSkill
- whatsappSkill
The file
Files
Semver: when to release, and which number
A version names a release people can install (semver.org). Changes pile up on the main branch unversioned; the number moves only when a release is cut.
The rule
- An ordinary change commits without touching the version and without a tag - a fix, a tweak and a feature alike.
- A release happens only when the user asks for one ("ship it", "release", "cut a version") or approves your suggestion to cut one.
- A release is one commit plus one tag: the commit sets every version
field to the new number, and
vX.Y.Ztags that commit. Where pushing a tag publishes (a release workflow on tags), push it only when the user asked to ship.
Earlier commits that bumped the version every time are not precedent to follow; they are the mess this rule exists to stop.
Installing a dev or ad hoc build on your own machine or phone is not a release and needs no version.
Suggesting a release
Suggest one, never cut it, when a user-visible change is finished and verified and the user will want it installed, or when several unreleased changes have piled up:
Unreleased since v1.5.0: global shortcut setting, panel spacing fix. Suggest v1.6.0 (minor: new setting). Ship it?
While the user is still iterating on how something looks or feels, offer the
local dev build (just run, just dev) instead, and release once they are
happy - not once per iteration.
Which number
Compare the whole release to the previous tag; the highest-impact change decides.
| Bump | When the release... |
| major | breaks something users relied on or makes them act: removed feature, renamed URL scheme / CLI flag / config key, one-way data migration, new required setup |
| minor | adds a capability users can see or call, backwards compatible: new feature, setting, command, option, endpoint |
| patch | only fixes and polishes: bug fix, layout or copy tweak, performance, refactor, dependency update |
- Several tweaks to a feature after it shipped go out as one patch, not a patch each.
0.y.zis initial development: a breaking change bumps minor. Go to1.0.0once something depends on it or it is in daily use.- Pre-release suffixes (
-beta.1) only when the pipeline actually ships pre-releases to a separate channel.
One source of truth
The tag is the release's identity. A version the build stamps (Info.plist, package metadata) equals the tag: set in the release commit, or better, derived from the tag by CI. Found a version field that disagrees with the latest tag? Report it; never "fix" it with another bump.
When a release fails
- Nothing reached users (CI failed before any GitHub release, artifact or package/cask update): fix it, delete the tag locally and on the remote, and re-tag the same version on the fix commit.
- Anything was published: that version is immutable. Fix forward with the next patch. Never move or force-push a published tag.
Red flags
| Thought | Reality |
| "Each earlier change got its own bump" | Precedent of the mess; commit without the bump |
| "I'll tag it so it's ready" | An unrequested tag is a release nobody asked for |
| "Bump now, release later" | An unreleased bump makes the next agent bump again |
| Patch release minutes after the last one for the same feature | Batch it; offer the dev build while iterating |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.