Changelog Maintenance
Use this skill when the deliverable is release history or shipped-change communication, not a broad documentation or launch-campaign bundle.
changelog-maintenance is the documentation-cluster anchor for:
CHANGELOG.md upkeep
- GitHub / GitLab / docs-site release notes
- migration and deprecation updates tied to a shipped change
- customer-facing “what changed” summaries
- lightweight game patch notes and small update posts
Read these support docs before choosing the mode or boundary:
- references/modes-and-boundaries.md
- references/output-packets-and-channel-handoffs.md
- references/release-note-quality-checklist.md
- references/automation-and-source-of-truth.md
When to use this skill
- A repo needs a durable changelog entry or
Unreleased refresh based on shipped work
- A release needs audience-appropriate notes for developers, customers, internal stakeholders, or players
- A breaking change, deprecation, or compatibility shift needs a migration update linked from release history
- Release automation drafted notes, but the output still needs truthful grouping, clearer wording, or better route-outs
- A game update needs concise patch notes without collapsing into marketing copy, deployment runbooks, or full help docs
- The real job is deciding the smallest release-writing packet rather than writing every neighboring document from scratch
When not to use this skill
- The main job is an internal spec, runbook, ADR, rollout plan, or deep migration procedure →
technical-writing
- The main job is published API / SDK / webhook / developer-portal content →
api-documentation
- The main job is end-user onboarding, tutorials, screenshots, FAQs, or help-center walkthroughs →
technical-writing
- The main job is deployment execution, environment promotion, rollback mechanics, or release orchestration →
deployment-automation
- The main job is launch copy, feature positioning, campaign sequencing, or GTM messaging →
marketing-automation
- There is no credible shipped evidence yet → collect proof first instead of inventing release notes from a roadmap or TODO list
Instructions
Step 1: Classify one primary release-writing mode
Normalize the request before drafting.
changelog_mode:
primary_mode: changelog | release-notes | migration-update | game-patch-notes
audience: developers | end-users | mixed | players | internal-stakeholders | unknown
release_scope: patch | minor | major | rolling | unknown
source_of_truth: release-pr | tagged-release | prs | issues | commits | docs | mixed | unknown
publishing_surface: changelog-file | github-release | docs-site | in-app-updates | steam-news | mixed | unknown
automation_context: manual | release-drafter | changesets | release-please | autogenerated-release-notes | mixed | unknown
output_shape: single-entry | summary-plus-links | migration-brief | patch-note-brief | sync-packet | unknown
Use one mode per run:
changelog → durable repo history in CHANGELOG.md
release-notes → audience-facing summary of what changed and why it matters
migration-update → changed behavior, required actions, deadlines, and compatibility notes
game-patch-notes → concise player-facing update summary
Step 2: Confirm audience, proof, and route-outs
Answer these before writing:
- Who reads this first?
- What action should they take after reading it?
- Which shipped evidence proves each headline claim?
- Which deeper artifact should carry the rest?
Quick route-out table:
| If the request sounds like... |
Use |
| “Write the architecture / rollout / runbook / internal migration plan” |
technical-writing |
| “Publish API reference, SDK docs, auth troubleshooting, or portal pages” |
api-documentation |
| “Write help docs, tutorials, screenshots, or FAQs for the changed workflow” |
technical-writing |
| “Plan deploy / rollback / release execution” |
deployment-automation |
| “Write launch copy / announcement / campaign messaging” |
marketing-automation |
| “Summarize shipped changes truthfully for a release surface” |
changelog-maintenance |
Step 3: Gather the smallest truthful evidence set
Do not write release history from memory alone. Pull the smallest credible packet first:
- merged release PR, tag, or release entry if it exists
- merged PRs / issues / commits included in the release
- linked migration docs, upgrade notes, or help docs
- breaking changes, removals, deprecations, deadlines, or rollout caveats
- publishing-surface constraints (
CHANGELOG.md, GitHub Release, customer update hub, Steam patch-note post)
- automation context, if any
If evidence is incomplete, label assumptions and missing proof explicitly.
Step 4: Choose the smallest useful artifact packet
Use references/output-packets-and-channel-handoffs.md.
Default shapes:
single-entry → one changelog entry or one release-note block
summary-plus-links → short release summary plus migration/help/API links
migration-brief → what changed, who is affected, required action, deadline, link-outs
patch-note-brief → concise new content / tuning / fixes / known issues packet
sync-packet → release-note draft plus list of downstream docs or channels that must stay aligned
Do not ship a broad handbook when one release packet and a short sync list will do.
Step 5: Apply mode-specific writing rules
- Changelog: favor grouped notable changes over commit archaeology; keep compare links or version/date framing when the repo uses them.
- Release notes: lead with impact, not internal ticket numbers; keep wording plain and scannable.
- Migration update: foreground required action, affected readers, deadline, and compatibility risk.
- Game patch notes: keep the note lightweight and player-facing; do not smuggle rollout mechanics or campaign copy into it.
Step 6: Keep record, communication, and promotion separate
Guard these boundaries aggressively:
- changelog / release notes summarize what shipped
- migration detail lives in linked migration docs when the procedure is too large for the summary
- tutorials / FAQs live in
technical-writing
- API and integration detail lives in
api-documentation
- rollout / rollback mechanics live in
deployment-automation
- campaign-style language lives in
marketing-automation
Step 7: Work with automation without surrendering judgment
Use automation as draft input, not the final editor.
- Release Drafter / autogenerated release notes → good for PR grouping and starter bullets
- Changesets → good for package/version intent and monorepo release aggregation
- release-please / semantic-release style flows → good for release PRs, version bumps, and commit-driven summaries
Still decide manually:
- the primary audience
- what counts as notable
- what needs a migration link
- what should become a separate help/API/internal doc
Step 8: Run the trust check before publishing
Use references/release-note-quality-checklist.md.
Verify:
- Every claim matches shipped or merged evidence.
- The chosen mode fits the audience and channel.
- Breaking changes, removals, and deadlines are impossible to miss.
- Route-outs stay explicit instead of bloating the note.
- The packet is as small as possible while still truthful.
Step 9: Return a brief or the finished artifact
Preferred brief shape before full drafting:
# Release Writing Brief
## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:
## Evidence used
- Source of truth:
- Supporting docs / links:
- Assumptions / missing proof:
## Planned artifact packet
1. main release artifact
2. downstream sync / linked-doc follow-up
## Writing notes
- Breaking changes / deadlines:
- Route-outs kept out of scope:
- Channel-specific constraints:
If the user already asked for the finished artifact, produce the selected packet directly with the matching structure.
Examples
Example 1: Changelog plus migration link
Input
Update CHANGELOG.md for v2.4.0 from the merged PR list and make the Basic Auth deprecation obvious.
Good output direction
- mode:
changelog
- output shape:
summary-plus-links
- grouped sections such as
Added, Changed, Deprecated, Fixed
- migration link or placeholder instead of embedding the full auth procedure
Example 2: Customer-facing release summary
Input
Turn these shipped product updates into release notes customers will actually read.
Good output direction
- mode:
release-notes
- output shape:
single-entry or summary-plus-links
- benefit-led headings like
What’s new, Improvements, Fixes
- route tutorials or help refreshes to
technical-writing
Example 3: Lightweight game patch notes
Input
Write patch notes for our latest game update and keep them short.
Good output direction
- mode:
game-patch-notes
- output shape:
patch-note-brief
- concise sections for new content, tuning, fixes, and known issues
- route launch-event hype or campaign beats to
marketing-automation
Best practices
- Start from shipped evidence, not vibes.
- Pick one primary audience and one primary mode.
- Use the smallest packet that fits the channel.
- Separate release summary, migration detail, help docs, API docs, rollout mechanics, and launch messaging.
- Let automation collect draft material, but do not outsource judgment.
- Call out breaking changes and deadlines early.
- Treat patch notes as a real workflow with player-facing constraints, not just a renamed changelog.
References
1---2name: changelog-maintenance3description: "Write and maintain release-history artifacts for shipped changes: `CHANGELOG.md` updates, release notes, migration/deprecation updates, and lightweight game patch notes. Use when the main job is turning shipped evidence into the smallest truthful release-writing packet for developers, customers, internal stakeholders, or players. Triggers on: changelog, release notes, patch notes, migration update, deprecation notice, version notes, what shipped, what changed, and what's new. Route internal specs/runbooks to `technical-writing`, API portals to `api-documentation`, end-user tutorials to `technical-writing`, rollout execution to `deployment-automation`, and launch messaging to `marketing-automation`."4license: MIT5compatibility: ">"6allowed-tools: Read Write Edit Glob Grep7metadata:8 source: https://skillmd.com/skills/akillness/changelog-maintenance9 tags: changelog, release-notes, patch-notes, migration, semantic-versioning, documentation, release-communication10 platforms: Claude, ChatGPT, Gemini11 version: 2.1.012 modernization: 2026-04-1413 hardening: 2026-04-1814---15161718192021# Changelog Maintenance2223Use this skill when the deliverable is **release history or shipped-change communication**, not a broad documentation or launch-campaign bundle.2425`changelog-maintenance` is the documentation-cluster anchor for:26- `CHANGELOG.md` upkeep27- GitHub / GitLab / docs-site release notes28- migration and deprecation updates tied to a shipped change29- customer-facing “what changed” summaries30- lightweight game patch notes and small update posts3132Read these support docs before choosing the mode or boundary:33- [references/modes-and-boundaries.md](references/modes-and-boundaries.md)34- [references/output-packets-and-channel-handoffs.md](references/output-packets-and-channel-handoffs.md)35- [references/release-note-quality-checklist.md](references/release-note-quality-checklist.md)36- [references/automation-and-source-of-truth.md](references/automation-and-source-of-truth.md)3738## When to use this skill39- A repo needs a durable changelog entry or `Unreleased` refresh based on shipped work40- A release needs audience-appropriate notes for developers, customers, internal stakeholders, or players41- A breaking change, deprecation, or compatibility shift needs a migration update linked from release history42- Release automation drafted notes, but the output still needs truthful grouping, clearer wording, or better route-outs43- A game update needs concise patch notes without collapsing into marketing copy, deployment runbooks, or full help docs44- The real job is deciding the smallest release-writing packet rather than writing every neighboring document from scratch4546## When not to use this skill47- **The main job is an internal spec, runbook, ADR, rollout plan, or deep migration procedure** → `technical-writing`48- **The main job is published API / SDK / webhook / developer-portal content** → `api-documentation`49- **The main job is end-user onboarding, tutorials, screenshots, FAQs, or help-center walkthroughs** → `technical-writing`50- **The main job is deployment execution, environment promotion, rollback mechanics, or release orchestration** → `deployment-automation`51- **The main job is launch copy, feature positioning, campaign sequencing, or GTM messaging** → `marketing-automation`52- **There is no credible shipped evidence yet** → collect proof first instead of inventing release notes from a roadmap or TODO list5354## Instructions5556### Step 1: Classify one primary release-writing mode57Normalize the request before drafting.5859```yaml60changelog_mode:61 primary_mode: changelog | release-notes | migration-update | game-patch-notes62 audience: developers | end-users | mixed | players | internal-stakeholders | unknown63 release_scope: patch | minor | major | rolling | unknown64 source_of_truth: release-pr | tagged-release | prs | issues | commits | docs | mixed | unknown65 publishing_surface: changelog-file | github-release | docs-site | in-app-updates | steam-news | mixed | unknown66 automation_context: manual | release-drafter | changesets | release-please | autogenerated-release-notes | mixed | unknown67 output_shape: single-entry | summary-plus-links | migration-brief | patch-note-brief | sync-packet | unknown68```6970Use one mode per run:71- `changelog` → durable repo history in `CHANGELOG.md`72- `release-notes` → audience-facing summary of what changed and why it matters73- `migration-update` → changed behavior, required actions, deadlines, and compatibility notes74- `game-patch-notes` → concise player-facing update summary7576### Step 2: Confirm audience, proof, and route-outs77Answer these before writing:781. Who reads this first?792. What action should they take after reading it?803. Which shipped evidence proves each headline claim?814. Which deeper artifact should carry the rest?8283Quick route-out table:8485| If the request sounds like... | Use |86|---|---|87| “Write the architecture / rollout / runbook / internal migration plan” | `technical-writing` |88| “Publish API reference, SDK docs, auth troubleshooting, or portal pages” | `api-documentation` |89| “Write help docs, tutorials, screenshots, or FAQs for the changed workflow” | `technical-writing` |90| “Plan deploy / rollback / release execution” | `deployment-automation` |91| “Write launch copy / announcement / campaign messaging” | `marketing-automation` |92| “Summarize shipped changes truthfully for a release surface” | `changelog-maintenance` |9394### Step 3: Gather the smallest truthful evidence set95Do not write release history from memory alone. Pull the smallest credible packet first:96- merged release PR, tag, or release entry if it exists97- merged PRs / issues / commits included in the release98- linked migration docs, upgrade notes, or help docs99- breaking changes, removals, deprecations, deadlines, or rollout caveats100- publishing-surface constraints (`CHANGELOG.md`, GitHub Release, customer update hub, Steam patch-note post)101- automation context, if any102103If evidence is incomplete, label assumptions and missing proof explicitly.104105### Step 4: Choose the smallest useful artifact packet106Use [references/output-packets-and-channel-handoffs.md](references/output-packets-and-channel-handoffs.md).107108Default shapes:109- `single-entry` → one changelog entry or one release-note block110- `summary-plus-links` → short release summary plus migration/help/API links111- `migration-brief` → what changed, who is affected, required action, deadline, link-outs112- `patch-note-brief` → concise new content / tuning / fixes / known issues packet113- `sync-packet` → release-note draft plus list of downstream docs or channels that must stay aligned114115Do not ship a broad handbook when one release packet and a short sync list will do.116117### Step 5: Apply mode-specific writing rules118- **Changelog**: favor grouped notable changes over commit archaeology; keep compare links or version/date framing when the repo uses them.119- **Release notes**: lead with impact, not internal ticket numbers; keep wording plain and scannable.120- **Migration update**: foreground required action, affected readers, deadline, and compatibility risk.121- **Game patch notes**: keep the note lightweight and player-facing; do not smuggle rollout mechanics or campaign copy into it.122123### Step 6: Keep record, communication, and promotion separate124Guard these boundaries aggressively:125- changelog / release notes summarize what shipped126- migration detail lives in linked migration docs when the procedure is too large for the summary127- tutorials / FAQs live in `technical-writing`128- API and integration detail lives in `api-documentation`129- rollout / rollback mechanics live in `deployment-automation`130- campaign-style language lives in `marketing-automation`131132### Step 7: Work with automation without surrendering judgment133Use automation as draft input, not the final editor.134- **Release Drafter / autogenerated release notes** → good for PR grouping and starter bullets135- **Changesets** → good for package/version intent and monorepo release aggregation136- **release-please / semantic-release style flows** → good for release PRs, version bumps, and commit-driven summaries137138Still decide manually:139- the primary audience140- what counts as notable141- what needs a migration link142- what should become a separate help/API/internal doc143144### Step 8: Run the trust check before publishing145Use [references/release-note-quality-checklist.md](references/release-note-quality-checklist.md).146147Verify:1481. Every claim matches shipped or merged evidence.1492. The chosen mode fits the audience and channel.1503. Breaking changes, removals, and deadlines are impossible to miss.1514. Route-outs stay explicit instead of bloating the note.1525. The packet is as small as possible while still truthful.153154### Step 9: Return a brief or the finished artifact155Preferred brief shape before full drafting:156157```markdown158# Release Writing Brief159160## Mode161- Primary mode:162- Why it fits:163- Audience:164- Output shape:165166## Evidence used167- Source of truth:168- Supporting docs / links:169- Assumptions / missing proof:170171## Planned artifact packet1721. main release artifact1732. downstream sync / linked-doc follow-up174175## Writing notes176- Breaking changes / deadlines:177- Route-outs kept out of scope:178- Channel-specific constraints:179```180181If the user already asked for the finished artifact, produce the selected packet directly with the matching structure.182183## Examples184185### Example 1: Changelog plus migration link186**Input**187> Update `CHANGELOG.md` for v2.4.0 from the merged PR list and make the Basic Auth deprecation obvious.188189**Good output direction**190- mode: `changelog`191- output shape: `summary-plus-links`192- grouped sections such as `Added`, `Changed`, `Deprecated`, `Fixed`193- migration link or placeholder instead of embedding the full auth procedure194195### Example 2: Customer-facing release summary196**Input**197> Turn these shipped product updates into release notes customers will actually read.198199**Good output direction**200- mode: `release-notes`201- output shape: `single-entry` or `summary-plus-links`202- benefit-led headings like `What’s new`, `Improvements`, `Fixes`203- route tutorials or help refreshes to `technical-writing`204205### Example 3: Lightweight game patch notes206**Input**207> Write patch notes for our latest game update and keep them short.208209**Good output direction**210- mode: `game-patch-notes`211- output shape: `patch-note-brief`212- concise sections for new content, tuning, fixes, and known issues213- route launch-event hype or campaign beats to `marketing-automation`214215## Best practices2161. Start from shipped evidence, not vibes.2172. Pick one primary audience and one primary mode.2183. Use the smallest packet that fits the channel.2194. Separate release summary, migration detail, help docs, API docs, rollout mechanics, and launch messaging.2205. Let automation collect draft material, but do not outsource judgment.2216. Call out breaking changes and deadlines early.2227. Treat patch notes as a real workflow with player-facing constraints, not just a renamed changelog.223224## References225- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)226- [Semantic Versioning 2.0.0](https://semver.org/)227- [Release Drafter](https://github.com/release-drafter/release-drafter)228- [Changesets](https://github.com/changesets/changesets)229- [release-please](https://github.com/googleapis/release-please)230- [GitHub Docs: Automatically generated release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)231- [Steamworks: Event Type — Small Update / Patch Notes](https://partner.steamgames.com/doc/marketing/event_tools/type_patchnotes?l=english)232- [Steamworks: Updating Your Game — Best Practices](https://partner.steamgames.com/doc/store/updates?l=english)