# Semantic Versioning

> Semantic Versioning

- Skill: `jzills/semantic-versioning` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jzills/semantic-versioning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jzills/semantic-versioning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jzills (https://skillmd.com/u/jzills)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jzills/semantic-versioning

---


# Semantic Versioning

## Overview

Determines the next semantic version number by inspecting git history and project conventions. Reports the computed version in conversation so calling skills can use it in branch names, tags, and release artifacts.

## Workflow

### Step 1 — Detect current version

Follow the priority order in `references/version-detection.md`:

1. Parse `git tag` for the highest SemVer-shaped tag (`vX.Y.Z` or `X.Y.Z`)
2. If no tags, inspect remote branches matching `release/*` patterns
3. If neither, assume `0.0.0`

### Step 2 — Gather evidence for bump type

- **Primary:** scan `git log <current-version>..HEAD` for conventional commit types
- **Fallback:** if no conventional commits found, read `CHANGELOG.md` Unreleased section

### Step 3 — Classify bump type

Apply the rules from `references/bump-inference.md`:

| Evidence | Bump |
|---|---|
| `BREAKING CHANGE:` footer or `!` suffix (e.g. `feat!:`) | major |
| Any `feat:` commit | minor |
| Only `fix:`, `perf:`, `refactor:`, `docs:`, `chore:`, `style:`, `test:` | patch |
| No conventional commits → CHANGELOG `### Removed` | major |
| No conventional commits → CHANGELOG `### Added` or `### Changed` | minor |
| No conventional commits → CHANGELOG only `### Fixed` | patch |

Always use the **highest** bump found across all evidence. If both sources are inconclusive, ask: "I couldn't determine the bump type automatically. Is this a major, minor, or patch release?"

### Step 4 — Compute next version

Apply the bump to the current version per SemVer 2.0.0 rules:

- `major`: increment X, reset Y and Z to 0 → `2.3.1` becomes `3.0.0`
- `minor`: increment Y, reset Z to 0 → `2.3.1` becomes `2.4.0`
- `patch`: increment Z only → `2.3.1` becomes `2.3.2`

### Step 5 — Report

Announce the result with reasoning:

> "The next version is **v2.1.0** (minor bump — 3 `feat:` commits detected since v2.0.1)"

The reported version is then available in the conversation for the calling skill to use.

## Using This Skill From Other Skills

When a skill needs the next version number before proceeding (e.g., naming a release branch or generating a tag), add this to the calling skill's SKILL.md:

```
**REQUIRED SUB-SKILL:** Invoke `semantic-versioning` to determine the release version.
The reported version (e.g. "v2.1.0") will be available in the conversation for use
in branch names, tags, and release artifacts.
```