# Version Bump
> Analyze branch changes against a base branch using conventional commits to determine and apply the correct semver version bump (major, minor, patch). Use this skill whenever the user asks to bump the version, release, update the version, prepare a release, determine what version to use, or analyze changes for versioning — even if they don't say "semver" or "conventional commits" explicitly. Use when this capability is needed.
- Skill: `tomevault-io/version-bump-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/version-bump-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/version-bump-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/version-bump-2
---
# Version Bump from Conventional Commits
Analyze the commits on the current branch compared to a base branch, determine the appropriate semantic versioning bump based on conventional commit messages, apply it, and run any version lifecycle scripts defined in package.json.
## How it works
Semantic versioning (major.minor.patch) maps directly to conventional commit types:
| Signal | Bump | Example commit |
| -------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------- |
| Any commit message containing `!` after the type (e.g. `refactor!:`, `feat!:`) or a `BREAKING CHANGE:` trailer | **major** | `refactor!: replace Axios with Ky` |
| `feat:` or `feat(scope):` (without `!`) | **minor** | `feat: add schedules endpoint` |
| Everything else (`fix:`, `chore:`, `docs:`, `refactor:`, `test:`, etc.) without `!` | **patch** | `fix: correct typo in endpoint` |
The highest-priority signal wins: if there is at least one breaking change, bump major regardless of how many features or fixes exist.
## Steps
1. **Identify the base branch.** Default to `main`. If the user specifies a different base (e.g., `develop`), use that instead.
2. **List commits.** Run:
```bash
git log ..HEAD --oneline
```
3. **Classify each commit** by its conventional commit prefix and the presence of `!` or `BREAKING CHANGE:` footer. Summarize the findings to the user grouped by category (breaking, features, fixes, other).
4. **Determine the bump.** Apply the priority table above.
5. **Check the current version** from `package.json`.
6. **Confirm with the user.** Present:
- The grouped summary of changes
- The current version
- The proposed new version
- The reasoning (which commits drove the decision)
Wait for the user to confirm or override before proceeding. If the user requests a different bump level, respect their choice.
7. **Apply the version bump.** Run:
```bash
npm version
```
This updates `package.json`, runs the `version` lifecycle script (which generates the CHANGELOG via `conventional-changelog`), commits `package.json` and `CHANGELOG.md`, and creates a git tag `v`.
8. **Report the result.** Show the new version and remind the user that the commit and tag have been created. They can publish with:
```bash
git push --follow-tags && npm publish
```
## Edge cases
- **No conventional commit prefixes**: If commits don't follow conventional commits, warn the user and ask them to specify the bump level manually.
- **Pre-release versions**: If the current version is already a pre-release (e.g., `1.0.0-beta.1`), ask the user whether to bump the pre-release or graduate to a stable release.
- **No changes**: If there are no commits ahead of the base branch, tell the user there's nothing to bump.
- **Monorepo**: This skill handles a single package.json. If the user is in a monorepo, ask which package to bump.
---
> Source: [tutkli/jikan-ts](https://github.com/tutkli/jikan-ts) — distributed by [TomeVault](https://tomevault.io).