Changelog Manager Skill

This skill provides an expert workflow for generating and maintaining high-quality, curated CHANGELOG.md files, combining the modular groupings of Keep a Changelog v1.1.0 with the stricter formatting and git-alignment rules of Common Changelog.

Core Philosophy

• Write for Humans: Changelogs are designed for human end-users and developers to understand the impact of a release. Avoid dumping raw git logs or conventional commits verbatim.
• Curated over Automated: While automation drafts, a human or expert agent must edit, rephrase, and merge related changes to eliminate noise.
• Git Alignment: A clean changelog is strengthened by a clean git history. Clean up commit/issue data prior to drafting.

Reference Guides (Progressive Disclosure)

For detailed formatting guidelines and examples, read the following specialized guides:

• Keep a Changelog Guide - Explains standard semantic categories (Added, Changed, Deprecated, Removed, Fixed, Security) and structural principles.
• Common Changelog Guide - Outlines strict curation standards, the use of Notice blocks, and bold impact prefixes.

---

Workflow

Follow these steps precisely when asked to generate or update a project's changelog:

1. Gather Change Sources

Collect data from all available project histories:

• Git Commits: Run git log --oneline -n 100 or search since the last tagged version.
• Beads Issues (bd): Run bd list --status closed --no-pager or export the beads database to JSON/JSONL using bd list --all --json to inspect closed tasks and completed epics.
• Release Tags: Run git tag -l to find existing version tags and their dates.

2. Check for an Existing CHANGELOG.md (CRITICAL)

Before writing any content, check if a CHANGELOG.md already exists at the project root:

• If it does NOT exist: Create a fresh file starting with the standard header:

  # Changelog
  
  All notable changes to this project will be documented in this file.
  
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
  and [Common Changelog](https://common-changelog.org/),
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

• If it DOES exist: Do NOT overwrite the entire file. You must read and update it carefully:
  • Preserve History: All past version blocks (e.g., ## [1.0.0] - YYYY-MM-DD and older) must remain completely unmodified.
  • Handling [Unreleased]:
    • If adding unreleased changes and an ## [Unreleased] block already exists, merge your new entries into the existing categories, avoiding duplicates.
    • If no ## [Unreleased] block exists, insert it directly below the main introduction header.
  • Drafting a New Release:
    • Change the existing ## [Unreleased] header to the new version header with today's date: ## [NEW_VERSION] - YYYY-MM-DD.
    • Insert a fresh, empty ## [Unreleased] block directly above this new version block.
    • Update the markdown reference links at the bottom of the file (e.g., update comparison URLs like [Unreleased]: https://github.com/owner/repo/compare/vNEW_VERSION...HEAD and add [NEW_VERSION]: https://github.com/owner/repo/compare/vOLD_VERSION...vNEW_VERSION).

3. Identify the Target Version and Date

• Determine if you are drafting an [Unreleased] section or preparing a specific version release (e.g., [1.0.0] - YYYY-MM-DD).
• Version headers must use the format ## [VERSION] - DATE (where VERSION is a valid semver version without the "v" prefix, and DATE is in the YYYY-MM-DD ISO-8601 format).

4. Add Optional Notices (Common Changelog)

Immediately below the release heading, you may include a single-sentence Notice paragraph in italics if applicable:

• For the initial release: _Initial release._
• For major upgrades: _If you are upgrading: please see [UPGRADING.md](UPGRADING.md)._
• For yanked releases or zero-code releases, clarify here.

5. Categorize Changes Strictly

Sort all notable changes into the six standard categories defined by Keep a Changelog:

1. ### Added - For new features.
2. ### Changed - For changes in existing functionality.
3. ### Deprecated - For soon-to-be removed features.
4. ### Removed - For now removed features.
5. ### Fixed - For any bug fixes.
6. ### Security - In case of vulnerabilities.

[!IMPORTANT] Never use custom category names. If a change doesn't fit, rephrase it so it fits one of the six standard categories. Avoid listing chores, CI/CD setup, or formatting tweaks unless they are highly notable for developers.

6. Curate and Rewrite (The Common Changelog Standard)

• Remove Noise: Filter out tracking commands (e.g., bd close, bd update, tracker refactors), tiny formatting commits, and minor merge commits.
• Synthesize Tasks: If a feature or bug was implemented across multiple small tasks/commits (e.g. abra-go-242.1, abra-go-242.2, abra-go-242.3), synthesize them into a single, high-quality, high-level entry.
• Signaling Impact (Prefixes): Bold key impact signals inside change items, especially for breaking changes or critical performance notes (e.g., - **Breaking:** remove write() method... or - **Performance:** transition to server-side cursor pagination...).
• Link to Issues/PRs: Add references to bd issue IDs (e.g. [abra-go-242]) or Pull Requests to give users full context.

7. Format and Write CHANGELOG.md

• List versions in reverse chronological order (newest on top).
• Use reference-style markdown links at the bottom of the file (e.g., [1.0.0]: https://github.com/owner/repo/releases/tag/v1.0.0) to keep the unrendered markdown clean and readable.