changelog

When to use

Trigger this skill when:

• A release (tag, version bump, deploy) needs user-facing release notes.
• A monthly or quarterly "what shipped" digest is needed for customers, a newsletter, or a developer blog.
• A CHANGELOG.md file needs an update before a merge to main.

Do not use this skill for:

• Internal engineering rollups (use status-update instead).
• Security advisories — those follow a separate disclosure process.
• Commit-level audit logs — use git log directly.

Inputs

Required:

• Repository (local path or GitHub URL).
• Version range — either two tags (v2.3.0..v2.4.0) or two dates (2026-03-01..2026-03-31) or a single tag to compare against the previous tag.
• Target version (the version being released, e.g., v2.4.0).

Optional:

• Audience — customer (default), developer, or internal. Affects filtering and tone.
• Path to existing CHANGELOG.md — the skill will prepend the new section rather than overwrite.
• PR label filters — if the repo uses labels like user-facing or changelog:skip, use them.

Outputs

A Markdown block in Keep a Changelog format, grouped by the following categories (in order):

1. Added — new features.
2. Changed — changes to existing functionality.
3. Deprecated — features marked for removal.
4. Removed — features removed in this release.
5. Fixed — bug fixes.
6. Security — security-impacting changes.

Each bullet is a single sentence describing user impact, not the implementation. Ticket and PR numbers may be suffixed in parentheses.

Tool dependencies

• Bash — git log, git tag, git diff --stat for scoping.
• GitHub MCP (strongly recommended) — list_pull_requests to pull titles, bodies, labels, and merge status.
• Read / Grep — to parse existing CHANGELOG.md and detect the previous version.

Procedure

1. Resolve version range. If the user gave two tags, use them. If one tag, find the previous tag via git describe --tags --abbrev=0 <tag>^. If dates, use --since and --until.
2. List merged PRs in range. Prefer GitHub MCP for metadata. For each PR: number, title, body, author, labels.
3. Filter out non-user-facing PRs. Drop PRs that are:
   • Labeled changelog:skip, internal, chore, ci, test, refactor, or docs:internal.
   • Titled with conventional-commit prefixes chore:, ci:, test:, refactor:, build:, style: (unless the body explicitly says "user-facing").
   • Touching only files under .github/, ci/, tests/, docs/internal/.
4. Categorize remaining PRs. Use both labels and conventional-commit prefixes:
   • feat: or label feature → Added.
   • fix: or label bug → Fixed.
   • perf: → Changed (with "Improved" phrasing) unless body says "fixes regression," then Fixed.
   • security: or label security → Security.
   • deprecate: or remove: or label breaking → Deprecated or Removed (read the body to decide).
   • Title starts with "Change X to Y" / "Update" → Changed.
5. Translate to user impact. For each PR, rewrite the title into a user-facing sentence. Examples:
   • feat(auth): add refresh token rotation → "Refresh tokens now rotate every 15 minutes, reducing the window in which a leaked token can be used."
   • fix(billing): off-by-one in proration calculation → "Fixed a rounding error in mid-cycle plan changes that occasionally charged $0.01 more than expected."
   • perf(api): memoize feature flag lookups → "Reduced p99 API latency by ~40ms for accounts with many feature flags."
6. Deduplicate. Multiple PRs that ship the same feature should collapse into one bullet.
7. Order within each section. Most user-impactful first. If the PR body includes an Impact: field, use it to rank.
8. Write the version header. ## [<version>] - <YYYY-MM-DD>. If this is the first release for the project, title the section ## [Unreleased] and let a human promote it at release time.
9. Prepend to existing CHANGELOG.md if one was provided. Do not overwrite.
10. Return the draft. Recommend a 5-minute skim by a PM or DevRel before publishing.