CHANGELOG.md + SemVer Release Prep
Updates CHANGELOG.md in Keep a Changelog format and picks the right SemVer bump from the actual diff, flagging breaking changes.
Before & after
Same prompt, same agent — the only difference is the skill.
Changelogs are a good way to communicate updates to your users. You'll want to list the features and bug fixes you've released. Be clear about what changed. Include any deprecations or breaking changes. You might want to highlight the most important updates. Think about what matters to your users. Different companies format changelogs differently. You could organize by version or date. It's good to be consistent with your format. What kind of updates are you planning to share?
CHANGELOG STRUCTURE (structured workflow, consistent format) PRE-WRITE PHASE: Gather facts (not interpretation) Git log extract (commits since last release) QA test results (what shipped, what's still in progress) User feedback channels (what people requested) Breaking change audit (any API or UX breaking points?) CHANGELOG ENTRY FORMAT: VERSION 2.4.0 — 2026-07-31 HIGHLIGHT: 'Faster calendar sync (40% speedup), now syncs Outlook' (One sentence that excites; lead with user benefit, not technical detail) NEW FEATURES: • Auto-book overlapping meetings to waitlist (inspired by customer feedback: 'We need batch scheduling') • Outlook calendar sync (formerly Google-only) • AI conflict resolution: If two priorities clash, AI suggests which to move (new, experimental) IMPROVEMENTS: • Calendar sync speed: 3 seconds → 2 seconds (40% faster) • Meeting description parsing: Now extracts attendee list from email (reduces manual entry) • Mobile UI: Larger buttons (44px, accessibility improvement) BUG FIXES: • Fixed: Recurring meetings on Friday appearing twice (issue #482) • Fixed: Time zone conversion breaking 12am-1am bookings (issue #519) • Fixed: Logout button invisible in dark mode (issue #501) DEPRECATIONS: • API endpoint /calendar/events/v1 (deprecated, migrate to v2 before 2026-10-31) • CalendarSync.sync() method → use CalendarSyncV2.syncOptimized() (3x faster) • CSS class .old-button-style → use .modern-button (will be removed in v2.5) KNOWN ISSUES: • Outlook sync not yet supported on Windows 7 (requires .NET Framework 4.8+) • Recurring daily events show UTC time instead of local time in list view (workaround: click event to view correct time) THANKS TO: • Contributors: Chen (UX), Sarah (backend optimization), test team (Outlook validation) • Customers who reported issues #482, #519 (you found the bugs we'd have shipped) RELEASE PROCESS: Ready to deploy: Changelog + release notes + product notification → all three ship together No changelog = no ship (blocks releases until documented)
About this skill
A wrong version number breaks your users' builds. This skill reads the commits and the diff, decides MAJOR, MINOR, or PATCH with evidence, and updates CHANGELOG.md exactly to spec.
What it does
- Classifies each change into Added, Changed, Deprecated, Removed, Fixed, Security
- Checks the diff (not just commit messages) for removed exports, signature changes, new defaults, and raised runtime minimums
- Applies SemVer 2.0.0, including the 0.y.z convention
- Moves Unreleased into a dated section and updates compare links
- Writes migration notes for major releases
What you get
A release prep report: proposed version with evidence, a CHANGELOG.md patch, migration notes, excluded changes, and a release checklist.
Best for
Maintainers of libraries, SDKs, CLIs, and public APIs with downstream users who depend on version numbers.
SKILL.md preview
---
name: changelog-semver-release
description: Maintain a project's CHANGELOG.md in Keep a Changelog 1.1.0 format and decide the correct Semantic Versioning bump - classify commits or PRs since the last tag, flag breaking changes, move Unreleased into a dated version section, and update compare links. Use when the user says "cut a release", "what version should this be?", "update CHANGELOG.md", "prepare v2.3.0", or maintains a library, SDK, API, or CLI with versioned consumers. Also triggers on "is this a breaking change?", "major or minor?", or "write release notes for these commits".
---
# CHANGELOG.md and SemVer Release Prep
… (sign up to view the full skill)More development skills
View all Development skills →CodeTour Walkthrough File Builder
Writes a valid CodeTour .tour file for your repo: persona-targeted steps anchored to verified file paths and line numbers.
Code-Accurate Docs: Docstrings, JSDoc, OpenAPI Specs
Docstrings, JSDoc/TSDoc, OpenAPI specs, and quickstart guides written from your real code, covering error paths and edge cases.
Markdown to Single-File HTML (Docs, Reviews, Slides)
Turns markdown into one offline-safe HTML file laid out as a document, diff review, or slide deck, with a fidelity report.
Release Changelog from Commits and PRs
Turns a commit range or merged PRs into a release changelog with breaking changes, migration steps, and user-facing wording.