agentleFS
Sign inStart free
mqmalagrismqmalagris/agent-skills/skills/semver/SKILL.md

semver

Skill0 starsChanged 8 days agoMITView on GitHub

Decide the correct Semantic Version bump for a change (major/minor/patch) by analyzing the diff against the project's public surface and running the ecosystem's breaking-change detector, then apply it (bump the manifest + changelog). Stack-agnostic, detects Rust/Cargo, npm/pnpm/yarn, Go modules, Elixir/Hex, Python, or a plugin.json/VERSION file from whatever manifest is present. Use when deciding a version bump, judging whether a change is breaking, choosing what version to release, reviewing an API or public-surface change for compatibility, or before tagging a release. Triggers on SemVer, semantic versioning, major/minor/patch, breaking change, "what version", "bump version", or /semver.

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Pre-1.0 (0.y.z): no compatibility guarantees.

    line 21
  2. Distinctive:

    Do not recite the spec; decide the bump for *this* diff, with evidence.

    line 63
  3. Distinctive:

    Do not guess "breaking" from a hunch when a detector exists for the ecosystem.

    line 64
  4. Distinctive:

    Do not bump MAJOR for an internal refactor, or PATCH a changed public signature.

    line 65
  5. Distinctive:

    Do not forget the 0.x convention: pre-1.0 breaking is a MINOR by custom, not a MAJOR.

    line 66
  6. Very specific:

    Do not reinvent version-file editing.

    line 67

“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

semver

Answer the question people get wrong: is this change breaking, and therefore what is the next version? The spec is trivial; the judgment is not. This skill decides the bump from evidence, then applies it. It is repo-agnostic: it works on any project that has versioning.

The rule (and the 0.x asterisk)

Given the last released version and the change since it:

BumpMeaningTrigger
MAJORBreakinganything a working consumer depends on could stop working (checklist below)
MINORFeaturebackward-compatible addition (new API / flag / optional field)
PATCHFixbehavior-preserving change (bugfix, docs, perf, internal refactor)

Pre-1.0 (0.y.z): no compatibility guarantees. By convention, bump MINOR for a breaking change and PATCH for everything else until you commit to 1.0. State which convention the project follows before recommending.

Workflow

  1. Resolve the change. Diff since the last release tag: git describe --tags --abbrev=0 then git diff <tag>...HEAD; fall back to the branch base if untagged. The unit is "what changed since the version consumers currently have."
  2. Detect the ecosystem from the manifest present (table below). It dictates both the public surface and the breaking-change tool.
  3. Run the breaking-change detector for that ecosystem (commands in REFERENCE.md). Read its output as evidence; do not eyeball. Degrade to a manual judgment (and say so) if no detector is installed.
  4. Classify each changed public item against the checklist. The highest-severity change wins the bump.
  5. Apply. Compute the new version, bump the manifest with the ecosystem's native command, add a Keep a Changelog entry, and tag vX.Y.Z if the project tags releases.

Is it breaking? (public surface, by consumer)

Assert only on what a consumer can observe. A change is breaking if their working usage could stop compiling or behaving:

SurfaceBreaking (MAJOR)Additive (MINOR)
Library / APIremoved or renamed exported symbol; changed signature, type, or return/error contract; new required parameter; narrowed input acceptancenew exported symbol; new optional parameter; widened acceptance
CLIremoved/renamed flag or command; changed default that changes behavior; changed output consumers parsenew flag/command; new opt-in output
HTTP / RPCremoved/renamed field or endpoint; changed status/error semantics; stricter validationnew endpoint; new optional field
Wire / serialization / schemalayout change old data or peers cannot readbackward- and forward-compatible field addition
Configremoved/renamed key; changed default behaviornew optional key with a safe default

Internal-only changes (private symbols, tests, docs, refactors with identical public behavior) are PATCH. Unsure if something is public? Check whether it is exported, documented, or reachable by a consumer; if not, it is internal.

Ecosystem detection

Manifest presentEcosystemDetector (see REFERENCE.md)
Cargo.tomlRustcargo semver-checks
package.jsonnpm / pnpm / yarnattw + api-extractor / api-diff
go.modGogorelease / apidiff (+ the v2+ import-path rule)
mix.exsElixirmanual public-surface review
pyproject.toml / setup.pyPythongriffe check
.claude-plugin/plugin.jsonagent-skillshand off to publish-skill --bump; collection releases per the repo's VERSIONING.md
VERSION / othergenericmanual, via the checklist

Output

State the bump (MAJOR / MINOR / PATCH), the exact new version, and the 1-3 changes that drove it (surface + why breaking). If nothing public changed, say PATCH and why. Then apply, or hand off to the project's release tooling.

Anti-patterns

  • Do not recite the spec; decide the bump for this diff, with evidence.
  • Do not guess "breaking" from a hunch when a detector exists for the ecosystem.
  • Do not bump MAJOR for an internal refactor, or PATCH a changed public signature.
  • Do not forget the 0.x convention: pre-1.0 breaking is a MINOR by custom, not a MAJOR.
  • Do not reinvent version-file editing; use the native command (npm version, cargo set-version, poetry version, or publish-skill).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free