Changelog Generator

Changelog Generator

Automated changelog generation following semantic versioning (SemVer) and Keep a Changelog standards. This skill guides agents through reviewing staged changes, determining appropriate version bumps, and updating both @package.json and @CHANGELOG.md files consistently.

Overview

The Changelog Generator skill automates the process of:

• Analyzing staged git changes to determine change types
• Calculating appropriate semantic version bumps (MAJOR.MINOR.PATCH)
• Updating the version in @package.json
• Generating properly formatted changelog entries in @CHANGELOG.md
• Ensuring consistency between version numbers and changelog entries

This skill follows the Semantic Versioning 2.0.0 specification and the Keep a Changelog format standards.

When to Apply

Reference this skill when:

• User requests to "update changelog" or "generate changelog"
• User asks to "bump version" or "create release"
• Preparing for a new release
• Need to document changes in a standardized format
• Ensuring version numbers follow semantic versioning
• Maintaining consistent changelog formatting

Preconditions:

• Git repository with staged changes
• Existing @package.json file with a version field
• Existing @CHANGELOG.md file following Keep a Changelog format
• Access to git commands (git diff, git status)

Workflow

The changelog generation process follows these 7 steps:

Step 1: Review All Staged Changes

Objective: Understand what changes have been staged and categorize them.

Actions:

1. Check git status to see what's staged:

   git status
   

2. Review all staged changes:

   git diff --cached
   

3. Analyze the changes to identify:

   • Breaking changes: API changes, removed features, incompatible changes
   • New features: Added functionality, new APIs, new components
   • Bug fixes: Fixes to existing functionality
   • Documentation: README updates, doc changes (usually don't affect version)
   • Refactoring: Code improvements without behavior changes (usually PATCH)

4. Review commit messages if available:

   git log --oneline --cached
   

Categorization Guidelines:

• Breaking changes → MAJOR version bump
• New features → MINOR version bump
• Bug fixes → PATCH version bump
• Documentation only → Usually no version bump (or PATCH if significant)
• Refactoring → Usually PATCH version bump

Output: List of categorized changes ready for changelog entry.

Step 2: Determine the Appropriate Version Bump

Objective: Calculate the new version number based on semantic versioning rules.

Actions:

1. Read current version from @package.json:

   # Read the version field
   cat package.json | grep '"version"'
   

2. Apply semantic versioning rules:

   • MAJOR (X.0.0): Increment when you make incompatible API changes

     • Breaking API changes
     • Removed features
     • Changed behavior that breaks existing code
     • Example: 1.2.3 → 2.0.0

   • MINOR (0.X.0): Increment when you add functionality in a backward-compatible manner

     • New features
     • New APIs (backward compatible)
     • Deprecated features (still functional)
     • Example: 1.2.3 → 1.3.0

   • PATCH (0.0.X): Increment when you make backward-compatible bug fixes

     • Bug fixes
     • Security patches
     • Performance improvements
     • Documentation updates (if versioned)
     • Example: 1.2.3 → 1.2.4

3. Priority order: If multiple change types exist, use the highest:

   • MAJOR > MINOR > PATCH
   • If any breaking changes exist → MAJOR
   • Else if any new features exist → MINOR
   • Else → PATCH

Decision Tree:

Are there breaking changes?
├─ Yes → MAJOR version bump (X.0.0)
└─ No → Are there new features?
    ├─ Yes → MINOR version bump (0.X.0)
    └─ No → PATCH version bump (0.0.X)

Output: New version number (e.g., 1.2.4).

Step 3: Update @package.json Version Accordingly

Objective: Update the version field in the root @package.json file.

Actions:

1. Read the current @package.json file
2. Locate the "version" field (usually near the top)
3. Update the version number to the new version determined in Step 2
4. Preserve all formatting:
   • Keep the same indentation (spaces or tabs)
   • Maintain the same JSON structure
   • Don't modify other fields
   • Don't reorder fields
   • Keep trailing commas if they exist

Example:

// Before
{
  "name": "qa-skills",
  "version": "0.4.0",
  "private": true,
  ...
}

// After (PATCH bump)
{
  "name": "qa-skills",
  "version": "0.4.1",
  "private": true,
  ...
}

Important:

• Only update the version field
• Don't change any other content
• Maintain JSON validity
• Preserve file formatting and style

Output: Updated @package.json with new version number.

Step 4: Update @CHANGELOG.md with a New Version Block

Objective: Add a new version section to @CHANGELOG.md following Keep a Changelog format.

Actions:

1. Read the current @CHANGELOG.md file
2. Locate the ## [Unreleased] section (should be at the top)
3. Insert a new version block after ## [Unreleased] and before the previous version
4. Use the format: ## [X.Y.Z] - YYYY-MM-DD
   • X.Y.Z is the new version number
   • YYYY-MM-DD is the current date (see Step 5)

Example Structure:

# Changelog

## [Unreleased]

## [0.4.1] - 2026-01-25

### Added
- New feature description

## [0.4.0] - 2026-01-25
...

Important:

• Place new version block between [Unreleased] and the previous release
• Use exact format: ## [X.Y.Z] - YYYY-MM-DD
• Maintain consistent spacing with existing entries
• Don't modify existing version entries

Output: @CHANGELOG.md with new version header added.

Step 5: Add the Version and the Date

Objective: Ensure the version block has the correct version number and current date.

Actions:

1. Get the current date in YYYY-MM-DD format

   • Use system date/time information
   • Never assume or hardcode dates
   • Format: YYYY-MM-DD (e.g., 2026-01-25)

2. Verify the version number matches Step 2 and Step 3

   • Version in changelog header must match @package.json version
   • Format: [X.Y.Z] where X, Y, Z are numbers

3. Update the version block header if needed:

   ## [0.4.1] - 2026-01-25
   

Date Format Rules:

• Always use YYYY-MM-DD format
• Use 4-digit year
• Use 2-digit month (01-12)
• Use 2-digit day (01-31)
• Match the format of existing changelog entries

Example:

## [1.2.4] - 2026-01-25

Output: Version block with correct version number and date.

Step 6: Add the Changelog Data

Objective: Populate the version block with categorized change entries.

Actions:

1. Organize changes from Step 1 into appropriate sections

2. Use the standard Keep a Changelog sections:

   • ### Added - New features
   • ### Changed - Changes in existing functionality
   • ### Deprecated - Soon-to-be removed features
   • ### Removed - Removed features
   • ### Fixed - Bug fixes
   • ### Security - Security vulnerabilities

3. Format each entry:

   • Use bullet points with - prefix
   • Start with a capital letter
   • End without a period (unless it's a full sentence)
   • Be concise and descriptive
   • Focus on user-facing changes

4. Section Guidelines:

   • Added: New features, new APIs, new components, new capabilities
   • Changed: Modified behavior, API changes (non-breaking), improvements
   • Deprecated: Features marked for removal in future versions
   • Removed: Features that were removed (usually indicates MAJOR bump)
   • Fixed: Bug fixes, corrections, patches
   • Security: Security-related fixes and improvements

5. Only include sections that have changes

6. Order sections: Added, Changed, Deprecated, Removed, Fixed, Security

Example:

## [0.4.1] - 2026-01-25

### Added
- New changelog generator skill for cursor agents
- Support for semantic versioning automation

### Fixed
- Corrected version bump logic for patch releases
- Fixed date formatting in changelog entries

### Changed
- Improved changelog entry categorization

Writing Guidelines:

• Write from the user's perspective
• Use present tense ("Adds feature" not "Added feature")
• Be specific but concise
• Group related changes together
• Avoid technical jargon when possible
• Focus on what changed, not how it was implemented

Output: Complete version block with all categorized changes.

Step 7: One Final Review

Objective: Verify everything is correct and consistent before completion.

Checklist:

1. Version Consistency:

   • Version in @package.json matches version in @CHANGELOG.md header
   • Version format is correct (X.Y.Z where X, Y, Z are numbers)

2. Date Format:

   • Date is in YYYY-MM-DD format
   • Date matches current date (not future or past)
   • Date format matches existing changelog entries

3. Changelog Content:

   • All staged changes are represented in the changelog
   • Changes are in the correct sections
   • No duplicate entries
   • Entries are clear and descriptive

4. Formatting:

   • Markdown formatting is correct
   • Version block is in the correct location (after [Unreleased])
   • Proper spacing between sections
   • Consistent with existing changelog style

5. Semantic Versioning:

   • Version bump type matches change types (MAJOR/MINOR/PATCH)
   • Breaking changes → MAJOR bump
   • New features → MINOR bump
   • Bug fixes → PATCH bump

6. File Integrity:

   • @package.json is valid JSON
   • @CHANGELOG.md is valid markdown
   • No syntax errors
   • Files are properly formatted

If any issues are found:

• Fix them before completing
• Re-verify the checklist
• Ensure consistency across all files

Output: Verified and consistent changelog and version updates.

File References

This skill references files using the @ syntax convention:

• @package.json: The root package.json file in the repository

  • Contains the version field that needs updating
  • Located at the repository root

• @CHANGELOG.md: The changelog file following Keep a Changelog format

  • Contains version history and change documentation
  • Located at the repository root
  • Format: Markdown with version blocks

Usage in skill: When the skill mentions @package.json or @CHANGELOG.md, it refers to these specific files at the repository root. Always read these files before making changes and verify their current state.

Semantic Versioning Rules

Follow Semantic Versioning 2.0.0 specification:

Version Format: MAJOR.MINOR.PATCH

• MAJOR version (X.0.0): Increment when you make incompatible API changes

  • Breaking changes to public APIs
  • Removed features or functionality
  • Changed behavior that breaks existing code
  • Example: 1.2.3 → 2.0.0

• MINOR version (0.X.0): Increment when you add functionality in a backward-compatible manner

  • New features added
  • New APIs (backward compatible)
  • Deprecated features (still functional)
  • Example: 1.2.3 → 1.3.0

• PATCH version (0.0.X): Increment when you make backward-compatible bug fixes

  • Bug fixes
  • Security patches
  • Performance improvements
  • Documentation updates (if versioned)
  • Example: 1.2.3 → 1.2.4

Pre-release and Build Metadata

• Pre-release versions: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
• Build metadata: 1.0.0+20130313144700

For standard releases, use the three-part version number (X.Y.Z).

Decision Priority

When multiple change types exist:

1. Any breaking changes → MAJOR bump
2. Any new features (without breaking changes) → MINOR bump
3. Only bug fixes → PATCH bump

Keep a Changelog Format

Follow the Keep a Changelog format standards:

Structure

# Changelog

## [Unreleased]

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes in existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Security vulnerabilities

Section Guidelines

• Added: New features, capabilities, or functionality
• Changed: Modifications to existing functionality
• Deprecated: Features that will be removed in a future version
• Removed: Features that have been removed
• Fixed: Bug fixes and corrections
• Security: Security-related fixes and improvements

Formatting Rules

• Use ## for version headers: ## [X.Y.Z] - YYYY-MM-DD
• Use ### for change type sections: ### Added
• Use - for bullet points
• Date format: YYYY-MM-DD
• Only include sections that have changes
• Order: Added, Changed, Deprecated, Removed, Fixed, Security

Best Practices

• Write from the user's perspective
• Be clear and concise
• Group related changes
• Use present tense
• Focus on what changed, not implementation details
• Keep [Unreleased] section for future changes

Quick Reference

Git Commands

# Check staging status
git status

# Review staged changes
git diff --cached

# View commit history
git log --oneline --cached

Version Bump Examples

# Current: 1.2.3

# Breaking change → 2.0.0
# New feature → 1.3.0
# Bug fix → 1.2.4

Changelog Entry Template

## [X.Y.Z] - YYYY-MM-DD

### Added
- Description of new feature

### Changed
- Description of change

### Fixed
- Description of fix

Common Patterns

Pattern: Feature Release

• Changes: New features, no breaking changes
• Version: MINOR bump (0.X.0)
• Sections: ### Added, possibly ### Changed

Pattern: Bug Fix Release

• Changes: Only bug fixes
• Version: PATCH bump (0.0.X)
• Sections: ### Fixed

Pattern: Major Release

• Changes: Breaking changes
• Version: MAJOR bump (X.0.0)
• Sections: ### Removed, ### Changed, possibly ### Added

Pattern: Security Release

• Changes: Security fixes
• Version: PATCH bump (usually) or MAJOR (if breaking)
• Sections: ### Security, ### Fixed

Troubleshooting

Issue: Version mismatch between files

Solution: Ensure Step 3 and Step 4 use the same version number. Re-check both files.

Issue: Can't determine version bump type

Solution: Review Step 1 changes carefully. Use priority: MAJOR > MINOR > PATCH.

Issue: Changelog format doesn't match existing

Solution: Review existing @CHANGELOG.md entries and match their style exactly.

Issue: Missing changes in changelog

Solution: Re-run Step 1 to ensure all staged changes are reviewed and categorized.

References

• Semantic Versioning 2.0.0
• Keep a Changelog
• Git Documentation