Skills · Documents

DocumentsSkillDugout-created

/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

Claude Code: Tested
No outcomes reported yet
Claude apps: Not tested
No outcomes reported yet
Cursor: Not tested
No outcomes reported yet
Codex: Not tested
No outcomes reported yet
GitHub Copilot: Not tested
No outcomes reported yet

Compatibility labels come from our tests only. Community reports add detail but cannot mark an app as tested.

Editorial assessment · not a community rating

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 review

Setup 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

Claude Code: Tested
  1. Add the Skills Dugout marketplace once.
    /plugin marketplace add piyush-tkd/skillsdugout
  2. Install /changelog-why.
    /plugin install changelog-why@skillsdugout
  3. Start a new session and ask for it, for example "add a changelog entry for this".

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