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:
bash
```
git status
```
•
Review all staged changes:
bash
```
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:
bash
```
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:

bash

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

code

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:

json

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

markdown

# 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:
markdown
```
## [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:

markdown

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

markdown

## [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
•User-facing only: Do not mention component names, file paths, API endpoints, or internal utilities. Describe outcomes and benefits, not implementation details.

Output: Complete version block with all categorized changes.

Step 7: One Final Review

Objective: Verify everything is correct and consistent before completion.

Checklist:

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

markdown

# 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

bash

# Check staging status
git status

# Review staged changes
git diff --cached

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

Version Bump Examples

bash

# Current: 1.2.3

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

Changelog Entry Template

markdown

## [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.