| name | bump-version |
| description | This skill should be used when the user asks to "bump the version", "release a new version", "prepare a release", "update the version number", "version bump", or needs to determine and apply a semver version increment based on recent commits. |
Bump Version
Analyze commits since the last release tag and determine the appropriate semver version bump, then apply it using npm version.
Workflow
Follow these steps in order. Do not skip the confirmation step.
Step 1: Identify the Latest Tag
Run git tag --sort=-v:refname | head -1 to find the most recent version tag. Tags follow the v* pattern (e.g., v1.0.3).
Step 2: List Commits Since the Last Tag
Run git log <latest-tag>..HEAD --oneline to retrieve all unreleased commits. If there are no commits since the last tag, inform the user and stop.
Step 3: Determine the Version Bump Type
Analyze each commit message to classify the version bump:
- major — Any commit indicates a breaking change. Look for:
BREAKING CHANGE or BREAKING: in the message! after the type (e.g., feat!:, fix!:)
- minor — Any commit adds new functionality. Look for:
feat: or feat(scope): prefix- Commits describing new commands, options, or capabilities
- patch — All other changes. Common indicators:
fix:, deps:, chore:, docs:, refactor:, perf:, test:, ci: prefixes- Dependency bumps, bug fixes, maintenance tasks
Apply the highest applicable level: if any commit is major, bump major. If any commit is minor (and none are major), bump minor. Otherwise, bump patch.
Step 4: Confirm with the User
STOP — Do not proceed without user confirmation.
Present the analysis to the user:
- List the commits since the last tag
- State the recommended bump type and the reasoning
- Show what the new version number will be (current → new)
- Ask the user to confirm or choose a different bump type
Step 5: Update the Changelog
STOP — Read CHANGELOG.md before writing. Match the existing format and style.
Add a new entry at the top of CHANGELOG.md (below the # Changelog heading) for the new version:
- Use today's date and the new version number
- Add a compare link to the previous tag:
[X.Y.Z](https://github.com/waldekmastykarz/atifact/compare/vPREV...vX.Y.Z)
- Group changes into sections: Features, Bug Fixes, Maintenance (only include sections that apply)
- Write human-friendly descriptions, not raw commit messages
- Only include user-facing changes — skip dependency bumps, CI changes, and internal refactors unless they affect users (e.g., minimum Node.js version change is user-facing)
- Stage the file:
git add CHANGELOG.md
Step 6: Apply the Version Bump
Commit the staged changelog, then run npm version:
git commit -m "docs: update changelog for vX.Y.Z"
npm version <patch|minor|major>
The npm version command requires a clean working directory. Committing the changelog first ensures it runs without issues. npm version then updates package.json, creates a second commit, and tags it.
Step 7: Remind About Publishing
After bumping, remind the user to push the commit and tag to trigger the publish workflow:
git push && git push --tags
The GitHub Actions workflow automatically publishes to npm when a v* tag is pushed.
