| name | changelog-maintenance |
| description | 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 `user-guide-writing`, rollout execution to `deployment-automation`, and launch messaging to `marketing-automation`. |
| license | MIT |
| compatibility | > |
| allowed-tools | Read Write Edit Glob Grep |
| metadata | {"tags":"changelog, release-notes, patch-notes, migration, semantic-versioning, documentation, release-communication","platforms":"Claude, ChatGPT, Gemini","version":"2.1.0","modernization":"2026-04-14T00:00:00.000Z","hardening":"2026-04-18T00:00:00.000Z"} |
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:
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 →
user-guide-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.mdrelease-notes → audience-facing summary of what changed and why it mattersmigration-update → changed behavior, required actions, deadlines, and compatibility notesgame-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” | user-guide-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 blocksummary-plus-links → short release summary plus migration/help/API linksmigration-brief → what changed, who is affected, required action, deadline, link-outspatch-note-brief → concise new content / tuning / fixes / known issues packetsync-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
user-guide-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
user-guide-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
