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:

Check git status to see what's staged:
```
git status
```
Review all staged changes:
```
git diff --cached
```
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)
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:

Read current version from @package.json:

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

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
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:

Read the current @package.json file
Locate the "version" field (usually near the top)
Update the version number to the new version determined in Step 2
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:

Read the current @CHANGELOG.md file
Locate the ## [Unreleased] section (should be at the top)
Insert a new version block after ## [Unreleased] and before the previous version
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:

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)
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
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:

Organize changes from Step 1 into appropriate sections
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
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
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
Only include sections that have changes
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:

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)
Date Format:
- Date is in YYYY-MM-DD format
- Date matches current date (not future or past)
- Date format matches existing changelog entries
Changelog Content:
- All staged changes are represented in the changelog
- Changes are in the correct sections
- No duplicate entries
- Entries are clear and descriptive
Formatting:
- Markdown formatting is correct
- Version block is in the correct location (after [Unreleased])
- Proper spacing between sections
- Consistent with existing changelog style
Semantic Versioning:
- Version bump type matches change types (MAJOR/MINOR/PATCH)
- Breaking changes → MAJOR bump
- New features → MINOR bump
- Bug fixes → PATCH bump
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:

Any breaking changes → MAJOR bump
Any new features (without breaking changes) → MINOR bump
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.