mags-changelog
npx machina-cli add skill doancan/mags/mags-changelog --openclawMAGS Changelog
Generate a changelog from git history, optionally saving it to the project.
Steps
1. Gather git context
Run git log --oneline -30 via Bash to get the recent commit history. Note the latest tag if any (git describe --tags --abbrev=0 2>/dev/null).
2. Generate changelog
Call mags_generate_changelog to produce a structured changelog from the project state and git history.
3. Display output
Present the changelog with stats:
== Changelog ==
Generated from <N> commits since <last tag or "initial commit">
## [Unreleased]
### Added
- <feature description>
- <feature description>
### Changed
- <change description>
### Fixed
- <fix description>
### Removed
- <removal description>
---
Stats: <N> features | <N> changes | <N> fixes | <N> removals
Use the Keep a Changelog format (Added, Changed, Fixed, Deprecated, Removed, Security). Omit empty sections.
4. Ask to save
Ask the user: "Save this changelog? Options:"
- Append to
docs/changelog/changes.md - Create release as
docs/changelog/v<version>.md(ask for version number) - Skip and just display
If the user chooses to save:
- Check if the target file exists with
mags_get_doc. - If it exists, prepend the new entry at the top using
mags_update_doc. - If it does not exist, create it with
mags_create_doc. - Confirm: "Changelog saved to
<path>."
Related commands:
| Command | Description |
|---|---|
/mags-status | View project progress dashboard |
/mags-docs | List all project documents |
Source
git clone https://github.com/doancan/mags/blob/main/skills/mags-changelog/SKILL.mdView on GitHub Overview
Generates a structured changelog by mining recent git commits and the project state, formatted in Keep a Changelog style. It includes Added, Changed, Fixed, Removed, and a Stats line (e.g., Features/Changes/Fixes/Removals) and can be saved to docs/changelog locations to streamline release notes.
How This Skill Works
It collects recent commits with git log and detects the last tag, then feeds the data into mags_generate_changelog to produce a Keep a Changelog formatted output. The tool then presents the changelog and can save it via mags_get_doc, mags_update_doc, and mags_create_doc depending on whether the target file exists.
When to Use It
- Preparing a release and creating a formal changelog.
- Documenting new features or improvements in the Unreleased section.
- Tracking changes since the last tag for incremental releases.
- Sharing release notes with stakeholders or CI dashboards.
- Archiving historical changes for audits or documentation.
Quick Start
- Step 1: Gather git context with git log --oneline -30 and detect the last tag.
- Step 2: Generate the formatted changelog with mags_generate_changelog.
- Step 3: Save or display; choose Append to docs/changelog/changes.md or Create release in docs/changelog/v<version>.md; mags_get_doc/mags_update_doc/mags_create_doc handle persistence.
Best Practices
- Omit empty sections so the changelog stays concise.
- Use precise, user-facing descriptions for Added, Changed, Fixed, Removed, and Security.
- Keep a single Keep a Changelog format throughout releases.
- Check for an existing doc with mags_get_doc before saving.
- Save in a versioned path (e.g., docs/changelog/vX.Y.Z.md) when releasing.
Example Use Cases
- Changelog for v1.2.0 generated from recent commits and feature updates.
- Unreleased section populated with Added and Fixed items for the next release.
- Security fixes documented under the Security section.
- Deprecated features moved to Removed with brief notes.
- Changelog appended to docs/changelog/changes.md for ongoing maintenance.
