Skip to content

borghei/Claude-Skills / project-management/execution/release-notes

release-notes

Verified

Turn tickets, changelogs and git logs into user-facing notes grouped by type, breaking changes first. Use when announcing a product release, maintaining a changelog, or rewriting technical entries for customers.

Release Notes Expert

Overview

Transform raw technical changes -- tickets, changelogs, git logs, PRDs -- into clear, user-benefit-oriented release notes. This skill ensures every release communicates value to the right audience in the right tone, via a 5-step methodology: gather input, classify each change into one of five categories, rewrite for user benefit, adjust tone for the audience, and assemble.

When to Use

  • Product Releases -- Announcing new versions to customers, partners, or internal stakeholders.
  • Sprint Demos -- Summarizing what shipped for sprint review audiences.
  • Changelog Maintenance -- Keeping a running log of changes across releases.
  • Customer Communication -- Preparing release announcements for email, in-app, or documentation.

Core Capabilities

  • 5-category classification — New Features, Improvements, Bug Fixes, Breaking Changes, Deprecations with explicit assignment rules
  • User-benefit rewriting — lead with the outcome, plain language, 1-3 sentences; detects developer-perspective phrasing
  • Audience tone guidance — B2B/enterprise, consumer, developer/API, internal
  • Automated generation — release_notes_generator.py groups entries, formats markdown/JSON, and flags technical language for rewrite

Clarify First

Before generating the release notes, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

  • Audience: B2B/enterprise, consumer, developer/API, or internal (sets the entire tone matrix and how much detail to include).
  • Source changes: the tickets/PRs/changelog to translate, classified into the 5 categories (nothing generates without these).
  • Breaking changes & deprecations: what changed, the required action, and by when (forces the mandatory breaking-change fields that protect user trust).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Workflow

  1. Collect what shipped: cross-check Done tickets against the release diff; drop anything reverted.
  2. Write each entry for the reader [RECOMMENDED]: what they can now do, not what the team changed. Breaking changes state what changed, what the user must do, and by which date.
  3. Generate the grouped notes (categories with no entries are left out):
python3 project-management/execution/release-notes/scripts/release_notes_generator.py \
  --input project-management/execution/release-notes/assets/sample_release_entries.json \
  --product-name "Acme App" --version "2.5.0" --date 2026-11-08
  1. Verify: rewrite every entry listed under "Rewriting Suggestions" (the tool flags developer jargon such as "refactor", "endpoint", CamelCase or snake_case identifiers) or confirm it is right for the audience, and check customer copy for internal details before sending.

Input: {"entries": [{title, description, type, ticket_id}]} with type one of feature, improvement, bugfix, breaking, deprecation. Flags: --input F or --demo, --product-name, --version (both required), --date (default today; pass it for reproducible output), --format text|json.

Exit codes: 0 notes written; 2 missing file, invalid JSON, wrong shape, invalid entries or a bad --date.

Anti-Patterns

Notes for features that never shipped

Mistake: An item appears because its ticket was marked Done, but the code was reverted before release. Why it happens: The ticket tracker looks like the source of truth, so its Done list goes straight into changes.json. Instead: Before running release_notes_generator.py, cross-check Done tickets against the shipped commits (for example git log v4.1..v4.2). Flag any ticket that is missing from the diff for human review, and remove it if it didn't ship.

Marketing copy in place of specifics

Mistake: "Game-changing AI-powered insights now live across the platform!" with no behavior described. Why it happens: Hype feels like it drives adoption, and describing the exact behavior takes more work. Instead: Search for "revolutionary", "game-changing", "powered by AI" and "next-generation". Replace each with the specific behavior, the plans it is on, and how to turn it off.

One note for internal and external readers

Mistake: The customer email includes "known issue: occasional 502 on Safari, rollback in progress, on-call: @ana". Why it happens: Writing one note is faster, and the internal details feel like useful transparency. Instead: Produce two artifacts from the same source. The internal one carries known issues, on-call and rollback steps. The external one is value-framed with breaking changes first. Check customer copy for "rollback", "on-call" and internal known issues before sending.

Seven more, each with a bad and a good example: references/red-flags.md.

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

  • references/methodology-and-tooling.md — full 5-step methodology, classification tables, rewriting before/after examples, audience tone matrix, output template, troubleshooting, success criteria, and the release_notes_generator.py flag + JSON-schema reference. Read when producing notes or running the tool.
  • references/release-notes-guide.md — best-practices guide on category definitions, audience guidance, and worked examples. Read for the deeper rationale.
  • references/red-flags.md — concrete bad-vs-good entry examples and how to fix them. Read before publishing a draft.

Files

FilePurpose
scripts/release_notes_generator.pyGroups entries, flags jargon, renders markdown or JSON
assets/sample_release_entries.jsonSample entries incl. a breaking change and a deprecation
assets/release_notes_template.mdRelease notes document template
examples/wayfinder-v2-1-release-notes.mdWorked release

Integration Points

IntegrationDirectionDescription
sprint-retrospective/Receives fromSprint commit data and type distribution inform what changes to include
senior-pm/ComplementsStakeholder communication plans guide release note audience and tone
execution/create-prd/Receives fromPRD feature descriptions (Section 7) become release note entry drafts
scrum-master/Receives fromSprint review outputs identify what shipped and needs documentation
summarize-meeting/Receives fromRelease planning meeting summaries capture context for release notes
job-stories/ / wwas/Receives fromUser story descriptions inform user-benefit framing of entries

Scope & Limitations

In Scope:

  • Structured release note generation from JSON input with 5 entry categories
  • Automatic technical language detection with rewriting suggestions
  • Markdown and JSON output formatting with category grouping
  • Audience tone guidance (B2B, consumer, developer, internal)
  • Classification rules for New Features, Improvements, Bug Fixes, Breaking Changes, and Deprecations

Out of Scope:

  • Automatic extraction of changes from git history (see sprint-retrospective/ for git analysis)
  • Jira/Linear ticket integration for pulling completed stories (manual JSON input required)
  • Changelog maintenance across multiple releases (this tool generates per-release notes)
  • Distribution to email, in-app, or documentation channels (output is markdown/JSON for further processing)

Important Caveats:

  • The rewriting suggestions are pattern-based heuristics. They catch common technical language but cannot assess whether a description truly communicates user benefit.
  • Semantic versioning alignment is the user's responsibility. The tool does not validate that version numbers follow semver conventions relative to the change types present.
  • Breaking changes require special care. Always include: what changed, what the user must do, and by when. Vague breaking change notes erode user trust.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall