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)

1. 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

1. 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)

1. 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

1. 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

1. 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

1. 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

1. Only include sections that have changes
2. 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)

1. Date Format:

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

1. Changelog Content:

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

1. Formatting:

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

1. Semantic Versioning:

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

1. 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