borghei/Claude-Skills / project-management/execution/release-notes
release-notes
VerifiedTurn 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| assets/release_notes_template.md | markdown | 1.6 KB |
| assets/sample_release_entries.json | config | 1.7 KB |
| examples/wayfinder-v2-1-release-notes.md | markdown | 9.8 KB |
| references/methodology-and-tooling.md | markdown | 8.5 KB |
| references/red-flags.md | markdown | 10.5 KB |
| references/release-notes-guide.md | markdown | 5.1 KB |
| scripts/release_notes_generator.py | script | 11.8 KB |
references/release-notes-guide.md
View on GitHub# Release Notes Best Practices Guide
## Purpose
Release notes are the bridge between what your team built and what your users understand. They serve three functions: inform users of what changed, build trust through transparency, and drive adoption of new capabilities.
## Category Definitions
### New Features
Something that did not exist before. The user gains a capability they previously lacked.
**Test:** Could the user do this yesterday? If no, it is a new feature.
### Improvements
An existing capability that is now better -- faster, easier, more reliable, more accessible.
**Test:** Could the user already do this, but now it is better? If yes, it is an improvement.
### Bug Fixes
Something was broken and is now fixed. The software was not behaving as intended or documented.
**Test:** Was this a defect report or unexpected behavior? If yes, it is a bug fix.
### Breaking Changes
A change that requires the user to take action. Their existing workflow, integration, or configuration will stop working or behave differently without intervention.
**Test:** Will anything break for the user if they do nothing? If yes, it is a breaking change.
### Deprecations
A feature that still works today but will be removed in a future release. This gives users time to migrate.
**Test:** Does it still work but is scheduled for removal? If yes, it is a deprecation.
## Writing for Different Audiences
### B2B / Enterprise
- **Tone:** Professional, precise, confident
- **Emphasize:** Reliability, security, compliance, productivity gains
- **Avoid:** Casual language, exclamation marks, emojis
- **Include:** Impact on workflows, admin actions required, compliance implications
- **Example:** "Role-based access controls now support custom permission sets, enabling administrators to define granular access policies aligned with organizational security requirements."
### Consumer
- **Tone:** Friendly, conversational, enthusiastic (measured)
- **Emphasize:** Ease of use, delight, time saved, new possibilities
- **Avoid:** Technical jargon, implementation details
- **Include:** Visual descriptions, tips for getting started
- **Example:** "You can now organize your photos into custom albums. Tap the new Albums tab to get started."
### Developer / API
- **Tone:** Technical, direct, specific
- **Emphasize:** Endpoints, parameters, SDK versions, migration steps
- **Avoid:** Marketing language, vague descriptions
- **Include:** Code snippets, request/response examples, version numbers
- **Example:** "The `GET /v2/users` endpoint now accepts an optional `fields` query parameter for sparse fieldsets. See the API reference for supported field names."
### Internal Stakeholders
- **Tone:** Detailed, context-rich
- **Emphasize:** Business impact, metrics, team contributions
- **Avoid:** Over-simplification
- **Include:** Ticket IDs, team names, technical context as needed
## Distribution Channels
| Channel | Best For | Format |
|---------|----------|--------|
| **In-app notification** | All users, high visibility | Short summary with link to full notes |
| **Email** | Active users, subscription-based | Full notes or curated highlights |
| **Blog post** | Major releases, marketing value | Narrative format with screenshots |
| **Changelog page** | Developer audience, reference | Chronological, all versions |
| **Documentation** | API changes, migration guides | Technical, step-by-step |
| **Social media** | Brand awareness, feature highlights | Single feature spotlight |
| **Slack / Teams** | Internal stakeholders | Summary with links |
## Good vs Bad Examples
### Bad: Technical and self-centered
> - Updated React from v17 to v18
> - Refactored UserService to use repository pattern
> - Fixed NPE in ReportExportHandler.java line 234
> - Migrated auth to PKCE flow
### Good: User-benefit-oriented
> - **Smoother interactions** -- Page transitions and form updates are now noticeably faster and more responsive.
> - **Faster report exports** -- Reports that previously timed out now complete reliably, even for large date ranges.
> - **More secure sign-in** -- Your account is now protected by an upgraded authentication standard that works consistently across all browsers.
### Bad: Vague and unhelpful
> - Various bug fixes and improvements
> - Performance enhancements
> - Updated dependencies
### Good: Specific and actionable
> - **Fixed:** CSV exports now include all columns when custom fields are enabled. (BUG-3421)
> - **Faster:** Dashboard widgets load 40% faster on pages with more than 20 widgets.
> - **Updated:** The Python SDK now requires Python 3.9 or later. See the migration guide for upgrade instructions.
## Checklist Before Publishing
- [ ] Every entry leads with user benefit, not technical change
- [ ] No internal jargon, class names, or function references
- [ ] Breaking changes clearly state what the user must do
- [ ] Deprecations include a timeline and recommended alternative
- [ ] Tone matches the target audience
- [ ] Ticket IDs are included for traceability (if appropriate for audience)
- [ ] Empty categories are removed
- [ ] Release date and version number are correct
- [ ] Links to full changelog, support, and migration guides are included
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |