Changelog Update

Purpose

Generates changelog entries from git commits, categorizes changes into Added/Changed/Fixed/Breaking sections following configurable changelog format (default: keep-a-changelog), and updates or creates the changelog file for any project type.

Input Context

Requires:

• Project Configuration: Output from

  detect-project-type

  skill
• Version: New version number (e.g., "1.2.0")
• Custom Message (optional): User-provided commit message overrides auto-generation
• Last Tag: Git tag of previous release (optional)

Workflow

1. Load Changelog Configuration

Use configuration from

detect-project-type

:

• changelog_file

  - Path to changelog file (default:

  CHANGELOG.md

  )

• changelog_format

  - Format to use (default:

  keep-a-changelog

  )

• tag_pattern

  - For finding commits since last tag

2. Determine Changelog File Path

Use

changelog_file

from configuration:

changelog_file="CHANGELOG.md"  # from config, can be:
# - CHANGELOG.md (standard)
# - HISTORY.md (alternative)
# - CHANGES.rst (Python projects)
# - NEWS.md (GNU projects)
# - {package}/CHANGELOG.md (monorepos)

Check if file exists. If not, create with initial structure based on format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/).

3. Gather Commits

Get commits since last release tag:

if [ -n "$last_tag" ]; then
  git log ${last_tag}..HEAD --oneline --no-merges
else
  # First release - get all commits
  git log --oneline --no-merges
fi

For monorepo projects, optionally filter commits by package directory:

# Filter commits that touched this package only
git log ${last_tag}..HEAD --oneline --no-merges -- packages/my-lib/

3. Categorize Commits

Parse each commit message and categorize:

Added (new features):

• feat:

  or

  feat(scope):

• Commit messages starting with "add", "create", "implement"

Changed (modifications to existing features):

• Commit messages starting with "update", "modify", "change", "refactor"

• refactor:

  prefix

Fixed (bug fixes):

• fix:

  or

  fix(scope):

• Commit messages starting with "fix", "correct", "resolve"

Breaking Changes:

• BREAKING CHANGE:

  in body

• !

  after type (e.g.,

  feat!:

  )
• Extract breaking change description from body

Uncategorized:

• Other types (

  chore:

  ,

  docs:

  ,

  test:

  ,

  style:

  ) → skip or place in "Changed"

4. Format Changelog Entry

Generate entry following this format:

## Version {version} - {date}

### Breaking Changes
- Description of breaking change 1
- Description of breaking change 2

### Added
- New feature description 1
- New feature description 2

### Changed
- Change description 1
- Change description 2

### Fixed
- Bug fix description 1
- Bug fix description 2

Formatting rules:

• Date format: YYYY-MM-DD (use today's date)
• Strip conventional commit prefixes from descriptions
• Capitalize first letter of each entry
• Remove trailing periods
• Skip empty sections
• If custom message provided, use it for the entire entry

5. Insert Entry into Changelog

Read existing changelog file, parse structure, and insert new entry:

• Place after the file header (before any existing version entries)
• Preserve all existing entries unchanged
• Maintain consistent formatting (2 blank lines between versions)

6. Generate Commit Message

Create a commit message from the changelog content:

Release {scope} v{version}

{changelog-entry-body}

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Output Format

Return:

{
  "changelog_path": "plugins/daily-carry/CHANGELOG.md",
  "new_entry": "## Version 1.2.0 - 2026-01-12\n\n### Added\n- New deployment skill\n\n### Fixed\n- Version detection logic",
  "commit_message": "Release plugin:daily-carry v1.2.0\n\nAdded:\n- New deployment skill\n\nFixed:\n- Version detection logic\n\nCo-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>",
  "categories": {
    "added": 1,
    "changed": 0,
    "fixed": 1,
    "breaking": 0
  },
  "file_created": false
}

Examples

Example 1: Feature and Fix Commits

Input:

• Scope:

  plugin:daily-carry

• Version:

  1.2.0

• Last tag:

  daily-carry-v1.1.0

Commits:

feat: add deploy-otterstack command
fix: correct git push error handling
docs: update README with examples

Generated Entry:

## Version 1.2.0 - 2026-01-12

### Added
- Add deploy-otterstack command

### Fixed
- Correct git push error handling

Output:

{
  "changelog_path": "plugins/daily-carry/CHANGELOG.md",
  "new_entry": "## Version 1.2.0 - 2026-01-12\n\n### Added\n- Add deploy-otterstack command\n\n### Fixed\n- Correct git push error handling",
  "commit_message": "Release plugin:daily-carry v1.2.0\n\nAdded:\n- Add deploy-otterstack command\n\nFixed:\n- Correct git push error handling\n\nCo-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>",
  "categories": {
    "added": 1,
    "changed": 0,
    "fixed": 1,
    "breaking": 0
  },
  "file_created": false
}

Example 2: Breaking Change

Input:

• Scope:

  marketplace

• Version:

  2.0.0

Commits:

feat!: change marketplace schema structure

BREAKING CHANGE: marketplace.json now requires plugins array with explicit versions

Generated Entry:

## Version 2.0.0 - 2026-01-12

### Breaking Changes
- marketplace.json now requires plugins array with explicit versions

### Added
- Change marketplace schema structure

Example 3: Custom Message Override

Input:

• Scope:

  variants

• Version:

  1.2.0

• Custom message: "Update Android and TypeScript variants with new git workflow patterns"

Generated Entry:

## Version 1.2.0 - 2026-01-12

- Update Android and TypeScript variants with new git workflow patterns

Commit Message:

Release variants v1.2.0

Update Android and TypeScript variants with new git workflow patterns

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Example 4: First Release (No Commits to Parse)

Input:

• Scope:

  plugin:new-plugin

• Version:

  1.0.0

• No last tag

Generated Entry:

## Version 1.0.0 - 2026-01-12

### Added
- Initial release of new-plugin

Error Handling

• Git errors: Return error if git log fails
• File write errors: Return error if changelog file cannot be written
• Invalid date: Use current system date as fallback
• Empty commits: Generate minimal entry with "Initial release" or "Version bump"

Integration Notes

This skill is invoked by the

/release

command in Phase 3. The command will:

1. Display the generated changelog entry
2. Allow user to edit before finalizing
3. Use the commit message for git operations in Phase 6