npx claudepluginhub pjt222/agent-almanacThis skill uses the workspace's default tool permissions.
---
Generates changelog entries following Keep a Changelog format by reviewing Git history, classifying changes into Added, Changed, Deprecated, Removed, Fixed, Security categories with user-focused wording.
Generates CHANGELOG.md files in Keep a Changelog format with templates for Added, Changed, Deprecated, Removed, Fixed, and Security sections. Includes guidelines and examples for version history.
Share bugs, ideas, or general feedback.
Maintain a project changelog following the Keep a Changelog format. This skill covers creating a new changelog, categorizing entries, managing the [Unreleased] section, and promoting entries to versioned sections upon release. Adapts to R convention (NEWS.md) when detected.
Search for an existing changelog in the project root.
# Check for common changelog filenames
ls -1 CHANGELOG.md CHANGELOG NEWS.md CHANGES.md HISTORY.md 2>/dev/null
If no changelog exists, create one 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 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
For R packages, use NEWS.md with R convention formatting:
# packagename (development version)
## New features
## Bug fixes
## Minor improvements and fixes
Expected: Changelog file located or created with proper header and an Unreleased section.
On failure: If a changelog exists in a non-standard format, do not overwrite it. Instead, note the format difference and adapt entries to match the existing style.
Read the changelog and identify its structure:
[Unreleased] section with pending changes[1.2.0] before [1.1.0])For each section, identify the categories present:
Expected: Changelog structure understood, existing entries inventoried.
On failure: If the changelog is malformed (missing sections, wrong order), note the issues but do not restructure without confirmation. Add new entries correctly and flag structural issues for manual review.
For each change to be documented, classify it into one of the six categories:
| Category | When to Use | Example Entry |
|---|---|---|
| Added | New feature or capability | - Add CSV export for summary reports |
| Changed | Modification to existing feature | - Change default timeout from 30s to 60s |
| Deprecated | Feature marked for future removal | - Deprecate old_function()in favor ofnew_function()`` |
| Removed | Feature or capability removed | - Remove legacy XML parser |
| Fixed | Bug fix | - Fix off-by-one error in pagination |
| Security | Vulnerability fix | - Fix SQL injection in user search (CVE-2026-1234) |
Entry writing guidelines:
Expected: Each change assigned to exactly one category with a well-written entry.
On failure: If a change spans multiple categories (e.g., both adds a feature and fixes a bug), create separate entries in each relevant category. If the category is unclear, default to "Changed."
Insert categorized entries under the [Unreleased] section. Maintain category order: Added, Changed, Deprecated, Removed, Fixed, Security.
## [Unreleased]
### Added
- Add batch processing mode for large datasets
- Add `--dry-run` flag to preview changes without applying
### Fixed
- Fix memory leak when processing files over 1GB
- Fix incorrect timezone handling in date parsing
Only add categories that have entries; do not include empty category headings.
Expected: New entries added under [Unreleased] in the correct categories, maintaining consistent formatting.
On failure: If the Unreleased section does not exist, create it immediately below the header/preamble and above the first versioned section.
When cutting a release, move all Unreleased entries to a new versioned section:
## [1.3.0] - 2026-02-17[Unreleased] to the new section[Unreleased] empty (but keep the heading)## [Unreleased]
## [1.3.0] - 2026-02-17
### Added
- Add batch processing mode for large datasets
### Fixed
- Fix memory leak when processing files over 1GB
## [1.2.0] - 2026-01-15
### Added
- Add CSV export for summary reports
Update comparison links (if present at bottom):
[Unreleased]: https://github.com/user/repo/compare/v1.3.0...HEAD
[1.3.0]: https://github.com/user/repo/compare/v1.2.0...v1.3.0
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
For R NEWS.md, use the R convention:
# packagename 1.3.0
## New features
- Add batch processing mode for large datasets
## Bug fixes
- Fix memory leak when processing files over 1GB
# packagename 1.2.0
...
Expected: Unreleased entries moved to a dated versioned section; Unreleased section cleared; comparison links updated.
On failure: If the version number conflicts with an existing section, the version was already released. Check with apply-semantic-versioning to determine the correct version.
Verify the changelog meets format requirements:
# Check for duplicate version sections
grep "^## \[" CHANGELOG.md | sort | uniq -d
# Verify date format
grep "^## \[" CHANGELOG.md | grep -v "Unreleased" | grep -vE "\d{4}-\d{2}-\d{2}"
Expected: Changelog passes all format checks with no warnings.
On failure: Fix any format issues found: reorder sections, correct date formats, remove duplicates. Report issues that require human judgment (e.g., missing entries for known changes).
[Unreleased] section exists at the top (below header)apply-semantic-versioning -- Determine the version number that pairs with changelog entriesplan-release-cycle -- Define when changelog entries get promoted to versioned sectionscommit-changes -- Commit changelog updates with proper messagesrelease-package-version -- R-specific release workflow including NEWS.md updatescreate-github-release -- Use changelog content as GitHub release notes