Release Notes Skill

Generate changelogs from commits and closed issues with breaking-change detection.

release-noteschangelogdevelopmentdocumentation

Release Notes Skill

TL;DR

The Release Notes skill reads your git commits and closed issues between two tags or dates, groups them by type (features, bug fixes, breaking changes, deprecations), and generates a formatted changelog ready to publish. It turns the tedious “what changed since v2.3.1?” question into a one-command answer.

The quality of the output depends heavily on the quality of your commit messages. A repo with descriptive conventional commits produces excellent release notes automatically. A repo with messages like “fix stuff” and “wip” will produce notes that need significant human editing.

What it does

  • Reads commits between two git refs (tags, branches, or commit SHAs) and groups them by conventional commit type: feat, fix, docs, chore, refactor, perf, test.
  • Pulls linked issues and PRs from the commit messages and GitHub/GitLab API, enriching each changelog entry with the issue title and number.
  • Detects breaking changes by scanning for BREAKING CHANGE: footers in commit messages and ! in conventional commit types (e.g., feat!:), and surfaces them prominently at the top of the changelog.
  • Generates audience-specific versions — a technical changelog for developers (with PR numbers and commit hashes) and a user-facing “What’s New” summary for product announcements.
  • Suggests a semantic version bump based on the types of changes: breaking changes → major, new features → minor, bug fixes only → patch.
  • Outputs to multiple formats — Markdown for CHANGELOG.md, GitHub Release body, Slack announcement, or email newsletter.

Best for

Open-source library releases: Generate a complete CHANGELOG.md entry for each release, with links to every PR and issue. Users can see exactly what changed and why, which builds trust and reduces support questions.

SaaS product releases: Produce a “What’s New” post for your changelog page (like Intercom’s or Linear’s product updates) that highlights user-facing improvements without exposing internal refactoring details.

Developer relations: Create release announcement content for your blog, newsletter, or Twitter/X thread. The skill can generate a short-form announcement alongside the technical changelog.

Sprint retrospectives: Generate a summary of what shipped in the last sprint by running the skill against the sprint’s date range rather than version tags.

How to use (example)

Scenario: Generating release notes for a Node.js library v3.2.0

You’re releasing my-lib v3.2.0 and need a CHANGELOG.md entry and a GitHub Release body.

Input:

Generate release notes for my-lib from v3.1.0 to v3.2.0.

Commit range: v3.1.0..HEAD
Repository: github.com/myorg/my-lib

Output formats needed:
1. CHANGELOG.md entry (Markdown, technical, include PR numbers)
2. GitHub Release body (Markdown, user-facing, no internal chore commits)

Audience for format 2: JavaScript developers using the library

What the skill does:

  1. Fetches commits between v3.1.0 and HEAD via the GitHub API.
  2. Parses conventional commit messages and groups by type.
  3. Fetches linked PR titles and issue descriptions for enrichment.
  4. Scans for BREAKING CHANGE: footers — finds none.
  5. Suggests version bump: minor (new features present, no breaking changes).
  6. Generates both output formats.

Example output — CHANGELOG.md entry:

## [3.2.0] - 2026-03-28

### Features
- Add `retry` option to `fetch()` with exponential backoff (#142, @alice)
- Support streaming responses via `fetchStream()` (#138, @bob)

### Bug Fixes
- Fix race condition in connection pool under high concurrency (#151, @alice)
- Correct TypeScript types for `RequestOptions.timeout` (#147, @carol)

### Performance
- Reduce memory allocation in response parser by 40% (#144, @bob)

### Documentation
- Add migration guide from v2.x to v3.x (#149)

Example output — GitHub Release body:

## What's New in v3.2.0

**Retry support:** `fetch()` now accepts a `retry` option with configurable attempts and exponential backoff — no more manual retry logic in your application code.

**Streaming responses:** New `fetchStream()` method for handling large responses without buffering the entire body in memory.

**Bug fixes:** Fixed a race condition under high concurrency and corrected TypeScript types for `timeout`.

**Performance:** Response parsing is 40% more memory-efficient in this release.

[Full changelog](CHANGELOG.md) · [Migration guide](docs/migration.md)

Common variations:

  • Add exclude_types: ["chore", "test", "refactor"] to keep the user-facing notes clean.
  • Use group_by: "component" instead of group_by: "type" to organize notes by product area rather than change type.
  • Combine with issue triage to automatically include the resolved issue count in the release summary.

Permissions & Risks

Required permissions: Repo API (read commits, read issues/PRs)
Risk level: Low

The skill only reads repository data — it doesn’t push commits, create tags, or publish releases. The main risks are quality-related rather than security-related:

Missing breaking change detection: The skill detects breaking changes from conventional commit footers and ! prefixes. If your team doesn’t follow conventional commits, breaking changes may be buried in regular fix or feat commits with no special marker. The skill will miss them. This is the most dangerous failure mode — a changelog that doesn’t prominently flag breaking changes causes upgrade pain for your users.

Commit message quality dependency: The skill can only work with what’s in the commit history. Vague messages (“fix bug,” “update code,” “misc changes”) produce vague changelog entries. Before enabling this skill, consider adopting conventional commits and enforcing them with a commit-msg hook.

Semantic versioning alignment: The skill suggests a version bump based on commit types, but it can’t know whether a “feature” commit is truly user-facing or just an internal API change. Always review the suggested version bump before tagging.

Recommended guardrails:

  • Always review the generated notes before publishing — treat them as a first draft, not a final document.
  • Run the skill in preview mode first to see what it would generate without publishing.
  • Keep a human-written “highlights” section at the top of major releases that the skill doesn’t touch.

Troubleshooting

Breaking changes aren’t being detected
Your commits don’t use conventional commit format with BREAKING CHANGE: footers or ! prefixes. Either adopt conventional commits going forward, or add a manual override: specify breaking changes explicitly in the skill input.

Changelog includes internal chore commits that users don’t care about
Add exclude_types: ["chore", "ci", "test", "build"] to your configuration. You can also add a min_impact threshold to exclude commits that only touch test files or documentation.

PR titles are being used instead of commit messages
Some workflows squash commits on merge, leaving only the PR title in the history. Configure the skill to prefer PR titles in this case — they’re usually more descriptive than individual commit messages in a squash workflow.

Notes are missing commits from a specific contributor
Check whether those commits used a different email address than their GitHub account. Commits not linked to a GitHub account won’t have PR associations and may be harder to enrich with issue context.

Generated notes are too long for a GitHub Release body
Use max_entries_per_section: 5 to cap the number of entries per section, and add a “See full changelog” link to CHANGELOG.md for the complete list.

Alternatives

conventional-changelog — A Node.js CLI tool that generates changelogs from conventional commits. Highly configurable, widely used, and integrates with semantic-release for fully automated versioning and publishing. Requires conventional commit discipline; no AI enrichment of commit messages.

Release Drafter — A GitHub Action that drafts GitHub Releases automatically as PRs are merged, using PR labels to categorize changes. Simpler than a full skill; works well for teams that label PRs consistently. No semantic version suggestion.

Manual CHANGELOG.md — Writing release notes by hand gives you complete control over tone, emphasis, and what to include. Time-consuming but produces the highest-quality output for major releases. Many teams use automation for patch releases and write major release notes manually.

Links & sources

  • Conventional Commits specification: conventionalcommits.org
  • Semantic Versioning: semver.org
  • GitHub Releases API: docs.github.com/en/rest/releases
  • Related guide: Best Skills for Developers

Related Skills

Explore more AI skills in our directory.

Back to Skills