semantic-versioning · aj-geddes — Claude Code skill: SemVer and releases
A skill for automated SemVer versioning: conventional commits, semantic-release and changelog generation.
npx skills add aj-geddes/useful-ai-prompts --skill semantic-versioning -a claude-codeWhat semantic-versioning does
The skill lays out MAJOR.MINOR.PATCH rules and ties them to conventional commits. From commit messages the agent works out which bump is due: a breaking change, a new feature or a patch. The version gets set automatically instead of by hand.
Five reference guides live in references/: SemVer configuration, the conventional commits format, semantic-release setup, a version bumping script and changelog generation. The quick start shows a package.json with a release script that calls semantic-release, plus devDependencies such as @semantic-release/changelog, @semantic-release/git and @semantic-release/github. That is a Node stack, so you need npm and a configured repository.
The skill advises tagging releases in git and documenting breaking changes. It also warns against mixing features into patch releases and against bumping versions by hand in an inconsistent way. If your project already follows its own numbering scheme, the skill will not match it — you would have to move the commit history onto conventional commits first.
What it helps with
- set a version that matches the actual change
- build a changelog from commit history
- track breaking changes before a release
- wire semantic-release into CI
- move a team onto conventional commits
Example prompts for the agent
- set up semantic-release for this repository
- which version bump do the latest commits need?
- generate a changelog for the new release
How to install semantic-versioning
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill semantic-versioning -a claude-code2Manually: put the files in place
~/.claude/skills/semantic-versioning/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/semantic-versioning/
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill semantic-versioning -a codex2Manually: put the files in place
.agents/skills/semantic-versioning/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill semantic-versioning -a cursor2Manually: put the files in place
.cursor/skills/semantic-versioning/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aj-geddes/useful-ai-prompts semantic-versioning2Manually: put the files in place
.github/skills/semantic-versioning/SKILL.md1Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill semantic-versioning -a gemini-cli2Platform CLI
gemini skills install https://github.com/aj-geddes/useful-ai-prompts --path skills/semantic-versioningManually: put the files in place
.devin/skills/semantic-versioning/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aj-geddes/useful-ai-prompts --skill semantic-versioning -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about semantic-versioning
How do I install semantic-versioning in Claude?
Run npx skills add aj-geddes/useful-ai-prompts --skill semantic-versioning -a claude-code. The skill lands in ~/.claude/skills/semantic-versioning/SKILL.md.
What does semantic-versioning do?
It covers SemVer practice: the MAJOR.MINOR.PATCH format, conventional commits, automatic version bumping, git release tags and changelog generation.
What tooling does the skill rely on?
The example uses semantic-release with the plugins @semantic-release/changelog, @semantic-release/git and @semantic-release/github, plus conventional-changelog-cli.
Source text
SKILL.md · MIT
---
name: semantic-versioning
description: >
Implement semantic versioning (SemVer) with automated release management. Use
conventional commits, semantic-release, and version bumping strategies.
---
# Semantic Versioning
## Table of Contents
- [Overview](#overview)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Reference Guides](#reference-guides)
- [Best Practices](#best-practices)
## Overview
Establish semantic versioning practices to maintain consistent version numbering aligned with release significance, enabling automated version management and release notes generation.
## When to Use
- Package and library releases
- API versioning
- Version bumping automation
- Release note generation
- Breaking change tracking
- Dependency management
- Changelog management
## Quick Start
Minimal working example:
```yaml
# package.json
{
"name": "my-awesome-package",
"version": "1.2.3",
"description": "An awesome package",
"main": "dist/index.js",
"repository": { "type": "git", "url": "https://github.com/org/repo.git" },
"scripts": { "release": "semantic-release" },
"devDependencies":
{
"semantic-release": "^21.0.0",
"@semantic-release/changelog": "^6.0.0",
"@semantic-release/git": "^10.0.0",
"@semantic-release/github": "^9.0.0",
"conventional-changelog-cli": "^3.0.0",
},
}
```
## Reference Guides
Detailed implementations in the `references/` directory:
| Guide | Contents |
|---|---|
| [Semantic Versioning Configuration](references/semantic-versioning-configuration.md) | Semantic Versioning Configuration |
| [Conventional Commits Format](references/conventional-commits-format.md) | Conventional Commits Format |
| [Semantic Release Configuration](references/semantic-release-configuration.md) | Semantic Release Configuration |
| [Version Bumping Script](references/version-bumping-script.md) | Version Bumping Script |
| [Changelog Generation](references/changelog-generation.md) | Changelog Generation |
## Best Practices
### ✅ DO
- Follow strict MAJOR.MINOR.PATCH format
- Use conventional commits
- Automate version bumping
- Generate changelogs automatically
- Tag releases in git
- Document breaking changes
- Use prerelease versions for testing
### ❌ DON'T
- Manually bump versions inconsistently
- Skip breaking change documentation
- Use arbitrary version numbering
- Mix features in patch releases
© aj-geddes · MIT · aj-geddes/useful-ai-prompts
Similar skills
All skills for Git and GitHub →semantic-versioning by other authors comes first.
