commit-changelog

name	commit-changelog
description	Commit staged or dirty changes with a conventional commit message and update CHANGELOG.md under [Unreleased]. Use when the user says "commit", "commit and update changelog", or similar.

Commit & Changelog

This skill covers committing code changes and keeping CHANGELOG.md up to date. The changelog follows Keep a Changelog with Added, Changed, Deprecated, Removed, Fixed, and Security sections under [Unreleased].

Workflow

1. Inspect what changed

git status --short
git diff --stat

If there are only staged changes, work with those. If there are unstaged changes, ask the user whether to stage everything (git add …) or only specific files.

Also check whether a CHANGELOG.md exists:

cat CHANGELOG.md 2>/dev/null || echo "NO CHANGELOG"

2. Determine the change category

Read the diff to understand what changed, then map it to a Keep a Changelog section:

Change type	Section
New features or functionality	Added
Behavior changes, API tweaks	Changed
Bug fixes	Fixed
Removed features	Removed
Deprecations	Deprecated
Security fixes	Security

3. Write the changelog entry

Describe what changed from the user's perspective. Keep it concise (one line per entry). Group related changes under the same bullet.

If CHANGELOG.md does not exist, create it with the Keep a Changelog skeleton plus the new entry.

4. Update CHANGELOG.md

Insert the entry under ## [Unreleased]. For a new section, add the ### <Section> heading followed by the bullet(s). Keep existing entries intact.

Example edit:

## [Unreleased]

### Fixed
- GPT `chat_message_decoder` no longer crashes the BEAM process on unrecognized roles

## [0.0.7] — 2026-06-28

If the section already exists, append the new bullet to it instead of creating a duplicate heading.

5. Commit

Use a conventional commit message:

<type>: <short description>

<optional body with details>

Types: feat, fix, chore, docs, refactor, test, style, ci, perf.

Stage the changed source files plus CHANGELOG.md. Do not stage unrelated local files (e.g. notes.org, .env, scratch files) unless the user explicitly asks.

git add <source files> CHANGELOG.md
git commit -m "<type>: <description>"

6. Show the result

git log --oneline -1
git show --stat HEAD

Notes

• If the user is on a feature branch, keep the commit there; do not merge or push without asking.
• If [Unreleased] already has entries, add the new one after existing entries in the same section, or create a new section if the category differs.
• Avoid shell-interpreted characters (backticks, $, !) in commit messages by using single-quoted strings or a temp file.