Bump Release
Author semver-sorted CHANGELOG.md entries that follow Common Changelog human-first rules when cutting or documenting a release.
Overview
Bump Release is an agent skill most often used in Ship (also Operate) that generates Common Changelog–compliant CHANGELOG.md release sections for semver-tagged software.
Install
npx skills add https://github.com/paulrberg/agent-skills --skill bump-releaseWhat is this skill?
- Common Changelog reference: human impact, importance order, skip noise, link every change
- Requires filename CHANGELOG.md with top-level # Changelog heading
- Release headings ## VERSION - DATE with semver VERSION and ISO YYYY-MM-DD
- Optional reference-style version links to GitHub release tags
- Supports notices (upgrade guides, first release) and grouped change sections
- Releases sorted latest-first by semver
- DATE format YYYY-MM-DD ISO 8601
Adoption & trust: 1.6k installs on skills.sh; 62 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You tagged a release but your changelog is inconsistent, missing dates, or unreadable for users upgrading between semver versions.
Who is it for?
Solo OSS maintainers and indie devs who semver-tag on GitHub and want human-oriented release notes without memorizing common-changelog.org.
Skip if: Teams that only use GitHub auto-generated release notes with no CHANGELOG.md policy, or non-semver continuous deploy products.
When should I use this skill?
You need a new stable semver release documented in CHANGELOG.md following Common Changelog rules.
What do I get? / Deliverables
CHANGELOG.md gains a latest-first, semver-valid release section with grouped changes, optional upgrade notice, and link-ready version references aligned to your git tag.
- CHANGELOG.md release section with version, date, grouped changes, and optional notice/links
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ship is where versions ship to users; launch subphase covers release notes and communication artifacts tied to tags. Launch fits publishing versioned CHANGELOG sections, notices, and linked GitHub releases consumers read at ship time.
Where it fits
Draft ## 1.0.1 - 2019-08-24 with Fixed bullets and a reference link before publishing the GitHub release.
Add an upgrade notice pointing to UPGRADING.md ahead of a 2.0.0 breaking release section.
After a production hotfix tag, append a concise Fixed group without rewriting older releases.
How it compares
Template for Common Changelog prose structure, not a CI bump-version bot or semantic-release replacement by itself.
Common Questions / FAQ
Who is bump-release for?
Solo builders and small teams shipping semver-tagged software who maintain CHANGELOG.md for users and contributors.
When should I use bump-release?
Use it in Ship launch when drafting notes for a new tag; in Operate iterate when backfilling or correcting release documentation after a hotfix.
Is bump-release safe to install?
It guides markdown changelog edits only; review the Security Audits panel on this page before letting an agent modify release files in your repo.
SKILL.md
READMESKILL.md - Bump Release
# Common Changelog Stripped-down reference for generating changelogs. Full spec: <https://common-changelog.org/> ## Guiding Principles - Changelogs are for humans. - Communicate the impact of changes. - Sort content by importance. - Skip content that isn't important. - Link each change to further information. ## Format ### File Format Filename must be `CHANGELOG.md`. Content must be Markdown starting with: ```md # Changelog ``` Releases must be sorted latest-first by semver. There must be an entry for every new stable release. ### Release A release starts with a second-level heading: ```md ## VERSION - DATE ``` `VERSION` is semver-valid (no "v" prefix) matching a git tag (with optional "v" prefix). `DATE` is `YYYY-MM-DD` (ISO 8601). ```md ## 1.0.1 - 2019-08-24 ``` The version should link to further information. If hosted on GitHub, link to a GitHub release. Use reference-style links to keep raw Markdown readable: ```md ## [1.0.1] - 2019-08-24 ### Fixed - Prevent segmentation fault upon `close()` [1.0.1]: https://github.com/owner/name/releases/tag/v1.0.1 ``` After the heading, a release must contain either: 1. One or more change groups 2. A notice followed by zero or more change groups ### Notice A single-sentence paragraph with Markdown emphasis, used for upgrade guides, status clarification, or first releases: ```md ## [2.0.0] - 2020-07-23 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md)._ ``` ```md ## [1.0.0] - 2019-08-23 _First release._ ``` There can only be one notice per release. ### Change Group A change group starts with a third-level heading containing a category: ```md ### <category> ``` Categories must be one of (in this order): - `Changed` — changes in existing functionality - `Added` — new functionality - `Removed` — removed functionality - `Fixed` — bug fixes The heading is followed by an unnumbered Markdown list. Each item is a single line: a change, then references, then optional authors. ```md - Prevent buffer overflow ([#28](https://github.com/owner/name/pull/28)) ``` Sort the list: breaking changes first, then by importance, then latest-first. #### Change Write using imperative mood. Must start with a present-tense verb (e.g. `Add`, `Refactor`, `Bump`, `Document`, `Fix`, `Deprecate`). Each change must be self-describing, as if no category heading exists. Instead of: ```md ### Added - Support of CentOS - `write()` method ``` Write: ```md ### Added - Support CentOS - Add `write()` method ``` #### References Each change should reference a PR when available; fall back to a commit hash only if no PR exists. References are written after the change on the same line, wrapped in parentheses. Each reference must be a Markdown link. **Pull requests (preferred):** ```md ([#194](https://github.com/owner/name/issues/194)) ``` **Commits (fallback):** ```md ([`53bd922`](https://github.com/owner/name/commit/53bd922)) ``` When there are more than two references, only include the best starting point. #### Authors Author names are optional and should generally be omitted. Only include them in multi-contributor projects where attribution matters. #### Prefixes Breaking changes must be prefixed in bold: `**Breaking:** ` and listed before other changes per category: ```md ### Changed - **Breaking:** emit `close` event after `end` - Refactor `sort()` internals to improve performance ### Removed - **Breaking:** drop support of Node.js 8 ``` For subsystem prefixes: `**<subsystem> (breaking):** `: ```md - **Installer (breaking):** enable silent mode by default - **UI:** tune button colors for accessibility ``` ## Writing ### Remove Noise Exclude maintenance changes not interesting to consumers: - Dotfile changes (`.gitignore`, `.github`, `.gitlab`, etc.) - Changes to development-only dependencies - Minor code style changes - Formatting changes in documentation Do **not** exclude: - Refactorings (may have unintentional side effects) - Changes to supported