changelog_skill

Overview

This skill generates and maintains changelogs in the Keep a Changelog format, using Conventional Commits and Semantic Versioning to produce clear release notes. It inspects git history, categorizes commits, and outputs structured changelog sections in Markdown or JSON. The skill also suggests version bumps and can produce simplified release notes for GitHub releases.

How this skill works

The skill reads git history since the last tag or a specified range, parses commit messages using Conventional Commits conventions, and maps commit types to changelog categories (Added, Changed, Fixed, Deprecated, Removed, Security). It groups entries by category, highlights breaking changes, generates a formatted changelog section, and recommends a version bump based on detected changes. Outputs include standard Keep a Changelog Markdown, machine-friendly JSON, and compact release-note summaries.

When to use it

• Preparing a release and you need consistent, human-friendly release notes.
• Automating changelog updates in CI/CD before tagging and publishing.
• Auditing recent changes to decide a semantic version bump.
• Generating GitHub release notes from commit history.
• Maintaining an Unreleased section for ongoing work and contributors.

Best practices

• Use Conventional Commits (feat:, fix:, docs:, etc.) to ensure reliable categorization.
• Keep commit messages concise and use scopes where helpful (type(scope): description).
• Highlight breaking changes with the conventional '!' and a clear description.
• Filter out noisy commit types (ci:, chore:, test:) from the changelog output.
• Link to issues or PRs in entries when relevant and keep entries readable for non-devs.

Example use cases

• Run on CI to auto-generate CHANGELOG.md and commit before creating a tag.
• Produce a JSON changelog for consumption by release tooling or dashboards.
• Extract the new version section and feed it to gh release create for GitHub.
• Analyze commits since a specific tag or date to audit changes for compliance.
• Create a concise release-notes markdown for marketing and stakeholder announcements.