Changelog

Changelog

Every invocation creates a versioned release. Gathers commits since the last tag, writes a dated release entry in CHANGELOG.md, commits, tags, and pushes. Follows Keep a Changelog format and Conventional Commits conventions.

Step 1: Pre-Flight Checks

1. git status --porcelain must return empty (CHANGELOG.md exempt). If dirty, abort and tell the user to commit or stash first.
2. git fetch origin
3. Branch not behind remote: git rev-list --count HEAD..origin/$(git branch --show-current). If behind, abort and tell the user to pull first.

Step 2: Determine Version

If $ARGUMENTS contains a version (e.g., v1.2.0), use it directly.

Otherwise, auto-detect from commits since the last tag:

git tag --sort=-v:refname | head -1

If no tags exist, treat the current version as 0.0.0.

Scan commits: git log --pretty=format:"%s%n%b" ..HEAD. Apply the highest-priority rule:

| Priority | Signal | Bump | |----------|--------|------| | 1 | Breaking change — BREAKING CHANGE in body/footer, or type! suffix (feat!, fix!) | Major | | 2 | New feature — feat or feat(scope) prefix | Minor | | 3 | Bug fix or improvement — fix, perf, or other included types | Patch |

If all commits were filtered (docs, test, ci, chore only), report "No release needed" and stop.

Report the detected version before continuing:

Next version: X.Y.Z (bump — reason)
Commits since vCURRENT: N total (N included, N filtered)

Step 3: Check No Duplicate Tag

git tag -l vX.Y.Z. If the tag already exists, abort and report the conflict.

Step 4: Gather and Categorize Commits

1. Get all commits since the last tag: git log --oneline ..HEAD
2. Categorize using the mapping below.
3. Filter noise: always drop merge commits, ci:, chore:, test:, docs:, and style: commits. For refactor: commits, include only when the diff touches a public API, CLI flag, configuration schema, or user-facing output; otherwise drop.
4. Translate technical commits to user-friendly descriptions.

Step 5: Write Release Entry

1. If no CHANGELOG.md exists, create one with a header and footer links (detect remote URL with git remote get-url origin).
2. If CHANGELOG.md exists, read it and preserve all existing content.
3. Add a new versioned section ## [X.Y.Z] - YYYY-MM-DD with today's date, placed above existing version sections.
4. Remove any existing Unreleased section and its footer link.
5. Update footer comparison links.
6. Verify: Entry count matches categorized commit count (minus filtered).

Step 6: Commit, Tag, Push

1. git add CHANGELOG.md
2. git commit -m "Release vX.Y.Z"
3. git tag -a vX.Y.Z -m "Release vX.Y.Z - "
4. git push --follow-tags
5. Verify: git ls-remote --tags origin | grep vX.Y.Z and report the version, tag, and commit hash.

---

Commit Categorization

Map Conventional Commits prefixes to Keep a Changelog sections. See references/changelog_format.md for the full mapping, writing style, and anti-patterns.

| Commit Prefix | Changelog Section | |---------------|-------------------| | feat: | Added | | fix: | Fixed | | refactor: (user-visible) | Changed | | security: | Security | | docs:, test:, ci:, chore: | Filter out |

Always include: features, user-facing bug fixes, breaking changes, security fixes. Always filter: merge commits, internal refactors, test changes, CI config, typos.

Translate technical commits to user-friendly language:

• fix(auth): resolve JWT expiry edge case -> "Fixed session timeout issues for long-running sessions"
• feat(api): add /users endpoint -> "Added user management API endpoints"

Git Analysis Commands

# All commits since last tag
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD

# Commits between tags
git log --oneline v1.0.0..v1.1.0

# Current tags
git tag --sort=-v:refname | head -10

Output Format

# Changelog

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

## [1.1.0] - 2026-02-13

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

## [1.0.0] - 2026-02-01

### Added
- Initial release features

[1.1.0]: https://github.com/owner/repo/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/owner/repo/releases/tag/v1.0.0

Examples

User request: /changelog (no arguments, first time) Action: No CHANGELOG.md. Create from full git history. Auto-detect version as v0.1.0. Steps:

1. Auto-detect: v0.1.0 (patch — first release with features)
2. Generate CHANGELOG.md with ## [0.1.0] - 2026-02-13
3. git add CHANGELOG.md
4. git commit -m "Release v0.1.0"
5. git tag -a v0.1.0 -m "Release v0.1.0 - Initial release"
6. git push --follow-tags

Output: Released v0.1.0, tagged, and pushed.

User request: /changelog (existing CHANGELOG.md, new commits since last tag) Action: Auto-detect version. Write versioned entry. Commit, tag, push. Steps:

1. Auto-detect: v1.3.0 (minor — new feature commits detected)
2. Write ## [1.3.0] - 2026-02-13 entry to CHANGELOG.md
3. git add CHANGELOG.md
4. git commit -m "Release v1.3.0"
5. git tag -a v1.3.0 -m "Release v1.3.0 - Dark mode and CSV export"
6. git push --follow-tags

Output: Released v1.3.0, tagged, and pushed.

User request: /changelog v2.0.0 (explicit version) Action: Use provided version. Write versioned entry. Commit, tag, push. Steps:

1. Version: v2.0.0 (explicit, skip auto-detection)
2. Write ## [2.0.0] - 2026-02-13 entry
3. git add CHANGELOG.md
4. git commit -m "Release v2.0.0"
5. git tag -a v2.0.0 -m "Release v2.0.0 - Complete API redesign"
6. git push --follow-tags

Output: Released v2.0.0, tagged, and pushed.

User request: /changelog (no new commits since last tag) Action: All commits filtered. No release needed. Output: No release needed. All commits since v1.3.0 are docs/test/CI changes.

References

| File | Content | |------|---------| | references/changelog_format.md | Full Keep a Changelog spec, Conventional Commits mapping, writing style guide, anti-patterns, release workflow reference, complete example |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: costa-marcello
• Source: costa-marcello/skillkit
• License: MIT

Install and usage instructions live in the source repository linked above.