/changelog-why
Writes changelog entries that tell readers what changed for them and why, without invented claims.
Created by Piyush Baheti · Source: piyush-tkd/skillsdugout/tree/main/plugins/changelog-why
Who it is for
Anyone who keeps a changelog or release notes for users, customers or other teams.
When to use it
- A change alters what someone sees, can do or must do.
- An entry just repeats its title.
- You are not sure whether a change needs an entry at all.
Example
You ask
Add a changelog entry for SHOP-212. Discount codes are now matched regardless of case. Before, customers typing "save10" instead of "SAVE10" were told the code was invalid; 37 support complaints last month. Merged, not released yet.
It writes CHANGELOG.md
[Unreleased]
Fixed
- Discount codes are now matched regardless of upper or lower case. Before, customers who typed "save10" instead of "SAVE10" were told the code was invalid, and support logged 37 of those complaints last month. (SHOP-212)
Output is Markdown (.md), shown formatted. Sample run on 2026-10-03 with an illustrative shop scenario.
Evidence
Our test
No baseline test yet. We will publish one, with and without the skill, when testing is done.
Reported by the community, by app
Compatibility labels come from our tests only. Community reports add detail but cannot mark an app as tested.
Editorial review in progress
We have not finished testing this listing against doing the task without it. The verdict appears here when we have. Our team made this skill; it gets the same test as external work.
How we reviewSetup and customization
- Works with no setup after install.
- Keeps your existing changelog format; uses Keep a Changelog if there is none.
What it can access
- Reads
- The change and any existing changelog
- Changes
- Edits the changelog when you ask
Install
- Add the Skills Dugout marketplace once.
/plugin marketplace add piyush-tkd/skillsdugout - Install /changelog-why.
/plugin install changelog-why@skillsdugout - Start a new session and ask for it, for example "add a changelog entry for this".
Not tested in Claude apps yet. These steps follow Claude apps's documented skills folder.
- Turn on code execution in Settings, under Capabilities. Skills need it.
- Download the skill zip from this page.
- Open Customize, then Skills, and choose Upload a skill. Pick the zip.
Not tested in Cursor yet. These steps follow Cursor's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add changelog-why --app cursor - For one repository only, run it inside the repo and add --project.
- No Node.js? Download the zip from this page and unzip it into ~/.cursor/skills/.
Not tested in Codex yet. These steps follow Codex's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add changelog-why --app codex - For one repository only, run it inside the repo and add --project.
- No Node.js? Download the zip from this page and unzip it into ~/.codex/skills/.
Not tested in GitHub Copilot yet. These steps follow GitHub Copilot's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add changelog-why --app copilot - For one repository only, run it inside the repo and add --project.
- In VS Code, turn on the chat.useAgentSkills setting.
- No Node.js? Download the zip from this page and unzip it into ~/.copilot/skills/.
Community reviews
No reviews yet. Be the first to rate it after you try it.
Each review records the app, version, task and outcome; those outcomes feed the Evidence section. One rating per person; creators reply but cannot rate their own work.
No reviews yet. Be the first to rate it after you try it.
Source, license and versions
- Source
- github.com/piyush-tkd/skillsdugout/tree/main/plugins/changelog-why
- License
- MIT, as stated in the repository
- 0.1.0 · 2026-10-03 · First release.
Show the full skill instructions
Writing a changelog entry
Overview
A changelog is read by people deciding whether a change affects them. The title says what is now true; the why is the part that earns the page its place. If the project already has a changelog format, keep it and apply these rules inside it. If it has none, use Keep a Changelog.
When to use
Reader impact decides. Write an entry when someone using or operating the product will see a difference, gain something, or need to act. That includes an internal change — a new required env var, a changed script flag, a dropped runtime version — when readers must do something about it.
Write none when no reader would notice or act: refactors, tests, formatting, internal tooling, CI tweaks.
One entry per ticket or user-visible change, not per commit.
Quick reference
| Part | Rule |
|---|---|
| Section | Keep a Changelog: Added, Changed, Deprecated, Removed, Fixed, Security |
| Title | What is now true, in the user's words |
| Why | Required. The reason said out loud — the symptom somebody hit, or what they can now do |
| Reference | Ticket or PR id, if there is one |
| Placement | Under [Unreleased] until it ships. Move it under a version only when that version is released |
| Version and date | Whatever the release process stamps; never invent a version number or a release date |
Shape for Keep a Changelog:
## [Unreleased]
### Fixed
- Failed payments now show the provider's reason. Before, every failure read
"Payment declined", so support could not tell a blocked card from an expired one. (ABC-412)
Evidence
- State only what is known. Do not invent user complaints, adoption, time saved or measured improvements.
- "Support could not tell a blocked card from an expired one" needs a ticket, a report or a reading of the old behaviour behind it. If the reason is an expectation, word it as one: "so support can tell…".
- Merged is not released. Do not write "now live" or "rolled out" for something still unreleased.
Common mistakes
| Mistake | Instead |
|---|---|
| The why repeats the title | Name the symptom somebody hit, or what they can now do |
| One entry per commit | One per ticket or user-visible change |
| An entry for a refactor or a test | Write none |
| Describing the code change | Describe what the reader sees or must do |
| Claiming an outcome nobody measured | State the behaviour; leave out the claim |
Good why: "The partner could not parse our reply, so every failure looked identical from their console." Bad why: "The response format was fixed."
Another good one: "You open this page when something is already going wrong, and it was at its least readable exactly then — the switch you came to flip sat sixth of nine columns in a grid that scrolled sideways on a laptop."
Red flags — stop
- A deadline is the reason there is no entry
- The why could be guessed from the title
- An entry nobody would read and act on
- A section name that the changelog does not already use
- A benefit stated as fact with nothing behind it