---

name: changelog-generator description: > Analyzes git history between two refs to generate changelog entries. Understands conventional commits, computes net delta to avoid redundant entries, and produces Keep a Changelog formatted output. Use when preparing releases, documenting breaking changes, or summarizing development work between versions. license: MIT compatibility: Requires git and Python 3.10+. Works with any git repository. metadata: author: nexus-labs version: "1.0" allowed-tools: Bash(git:) Bash(python:) Read Write

Changelog Generator

Generates well-structured changelog entries by analyzing git history between two refs.

When to Use

• Preparing a release and need to document changes
• Summarizing work done between versions
• Identifying breaking changes before release
• Creating release notes for GitHub/NuGet

Quick Start

Copy# Generate changelog section for a new version
python skills/changelog-generator/scripts/generate.py \
  --from v0.0.1 \
  --to HEAD \
  --version 0.0.2

# Prepend to existing CHANGELOG.md
python skills/changelog-generator/scripts/generate.py \
  --from v0.0.1-alpha.19 \
  --to HEAD \
  --version 0.0.2-alpha.1 \
  --mode full \
  --output CHANGELOG.md

Parameters

Output Format

The tool generates Keep a Changelog formatted markdown:

Copy## [1.2.0] - 2026-01-19

### ⚠️ Breaking Changes
- Removed `ITypeRegistrar` interface

### Added
- New `IInjectableTypeProvider` interface

### Changed
- Source generation is now the default

### Fixed
- Plugin discovery in AOT scenarios

See FORMAT.md for the complete format specification.

How It Works

1. Extracts commit history between the two refs
2. Parses conventional commits (feat:, fix:, etc.) when present
3. Computes net delta to identify actual changes (ignoring churn)
4. Detects breaking changes from commit messages and API removals
5. Categorizes changes into standard Keep a Changelog sections
6. Deduplicates related commits into single entries
7. Formats output as parseable markdown

Conventional Commits Mapping

Examples

Generate Section Only

Copypython generate.py --from v1.0.0 --to v1.1.0 --version 1.1.0

Output goes to stdout, can be copied into CHANGELOG.md manually.

Update CHANGELOG.md Directly

Copypython generate.py \
  --from v1.0.0 \
  --to HEAD \
  --version 1.1.0 \
  --mode full \
  --output CHANGELOG.md

Inserts new section after the header, before previous versions.

Specify Custom Date

Copypython generate.py \
  --from v1.0.0 \
  --to v1.1.0 \
  --version 1.1.0 \
  --date 2026-02-01

Edge Cases

• Merge commits: Analyzed for their net effect, not individual commits
• Reverts: Paired with original commit and excluded if they cancel out
• Empty range: Returns empty section with comment
• Non-conventional commits: Categorized by file patterns and keywords
• Missing refs: Exits with error and helpful message

Integration with CI

The release workflow extracts the version section from CHANGELOG.md:

Copy- name: Extract Release Notes
  run: |
    VERSION="${GITHUB_REF_NAME#v}"
    awk -v ver="$VERSION" '
      /^## \[/ { if (found) exit; if (index($0, "[" ver "]")) found=1 }
      found { print }
    ' CHANGELOG.md

This requires CHANGELOG.md to follow the format specification exactly.