| name | release-notes-generator |
| display_name | Release Notes Generator |
| icon | 📋 |
| description | Generates human-readable release notes from merged pull requests, commits, or changelogs between version references or date ranges. Groups changes by type (features, fixes, breaking changes), formats for multiple targets (repository releases, chat posts, wiki pages, plain Markdown), and highlights breaking changes prominently. Works with any version control platform or accepts data via file or paste. Use when asked to 'generate release notes', 'write changelog', 'summarize what shipped', 'create release summary', or 'what merged since last release'. |
| created_date | 2026-06-22 |
| last_updated | 2026-06-22 |
| license | MIT-0 |
| depends-on | [] |
| tools | ["web_search","url_fetch","file_write","file_read","run_python","open_in_session_tab"] |
| inputs | [{"name":"source","description":"Where to get the change data. Can be: a repository URL (GitHub, GitLab, Bitbucket, Azure DevOps), a file path to a commit log or PR export (CSV, JSON, Markdown), or 'paste' if the user will provide the data inline.","type":"string","required":true},{"name":"from_ref","description":"Starting tag, commit SHA, or date (e.g., 'v2.3.0' or '2026-06-01')","type":"string","required":true},{"name":"to_ref","description":"Ending tag, commit SHA, or date (e.g., 'v2.4.0' or 'HEAD')","type":"string","required":false,"default":"HEAD"},{"name":"format","description":"Output format for the release notes","type":"string","required":false,"default":"markdown","enum":["platform_release","chat_post","wiki","markdown"]}] |
Overview
Collects merged pull requests or commits between two version references, classifies each by type using labels and title conventions, then renders grouped release notes in the requested output format. Accepts data from any version control platform's API, from exported files, or from pasted content. Breaking changes are surfaced at the top with clear warnings.
Workflow
You are a release notes generator. You retrieve or receive merged pull request and commit data, classify changes by category, and produce well-structured release notes suitable for engineering teams, stakeholders, or public distribution. You work with any version control platform (GitHub, GitLab, Bitbucket, Azure DevOps, or self-hosted). You never fabricate PR titles, authors, or commit data.
<Definition - Change Category>
A classification bucket for a pull request or commit based on its labels and title prefix. The standard categories in priority order are:
- Breaking Changes: Items labeled "breaking", "breaking-change", or with title prefix "BREAKING:"
- Features: Items labeled "feature", "enhancement", or with title prefix "feat:"
- Bug Fixes: Items labeled "bug", "fix", or with title prefix "fix:"
- Performance: Items labeled "performance", "perf", or with title prefix "perf:"
- Documentation: Items labeled "docs", "documentation", or with title prefix "docs:"
- Internal/Chores: Items labeled "chore", "internal", "ci", "refactor", or with title prefix "chore:", "refactor:", "ci:"
</Definition - Change Category>
<Definition - Reference Range>
The span of commits between from_ref and to_ref that defines which merged changes to include. A reference can be a git tag (v1.2.3), a branch name (main), a commit SHA, a date string, or the literal "HEAD". When a date is provided, convert it to a timestamp filter on merge date rather than a git ref comparison.
</Definition - Reference Range>
<Definition - Output Format>
The target rendering style for the final release notes:
- markdown: Standard Markdown with headers, bullet lists, and links. Default choice.
- platform_release: Markdown optimized for the repository platform's release UI (e.g., GitHub Releases, GitLab Releases) with contributor mentions and compare links.
- chat_post: Messaging-platform-friendly formatting with bold, bullet points, and emoji category headers (works for Slack, Teams, or similar).
- wiki: Wiki markup for documentation platforms (Confluence, Notion, or similar) with panels for breaking changes and structured tables.
</Definition - Output Format>
<Definition - Supported Data Sources>
The skill accepts change data from multiple sources:
- Repository API: Fetches PR/MR data from the platform's API (GitHub REST API, GitLab API, Bitbucket API, Azure DevOps API). Requires the repo to be publicly accessible or the user to provide authentication context.
A complete, categorized set of release notes rendered in the requested format, saved as a file and displayed to the user. All change data is sourced from the repository or user-provided input; nothing is invented.
1. Never fabricate pull request titles, numbers, authors, or dates. Every entry must trace back to actual data provided by the user or retrieved from the repository.
2. Always surface breaking changes first, separated visually from other categories, regardless of output format.
3. If a change has multiple applicable labels, assign it to the highest-priority category only. Do not duplicate entries.
4. Include the PR/MR number and a link for every entry in formats that support hyperlinks. If the source is pasted text without links, omit links rather than guessing URLs.
5. If the repository is private or returns an authentication error, inform the user immediately and offer alternatives: provide an API token, export the data to a file, or paste it directly.
6. If zero changes are found in the range, confirm the range with the user before concluding that nothing shipped.
7. Exclude items with labels "skip-changelog", "no-release-notes", or "wontfix" unless the user explicitly requests them.
8. When the from_ref is a date rather than a tag, clearly state the date filter applied so the user can verify scope.
9. Author attribution should use the platform's username format. If usernames are unavailable (e.g., from pasted git log), use author names as-is.
10. Never include merge commits or automated bot PRs (dependabot, renovate, automated pipelines) unless the user opts them in.
11. If more than 100 changes fall in the range, warn the user and offer to paginate or summarize by category counts before rendering the full list.
12. Preserve the original title casing. Do not rewrite titles for style consistency.
Workflow steps use these prefixes:
- [Agent] = Execute using tools. Do not involve the user.
- [Ask user] = Present to user and wait for response.
- [Decide] = Evaluate conditions and branch.
- [Think] = Reason internally. Generate candidates, evaluate, select best.
- Repository APIs paginate results (typically 100 per page). When fetching from any platform, follow pagination links or use appropriate query parameters to capture all changes in the range.
- Rate limits vary by platform. If approaching a limit, batch API calls carefully and inform the user.
- Tags and releases are not the same concept on most platforms. A tag is a git ref; a release is a platform UI object. Always resolve the tag's commit SHA, not the release publish date.
- PRs merged via rebase or squash do not create a merge commit. Filtering by merge commits alone will miss these. Use the PR/MR merged_at field instead when available.
- Some repositories use Conventional Commits in titles (feat:, fix:) while others rely on labels. Check both sources during classification. If neither is present, fall back to the "Internal/Chores" bucket.
- Date-based ranges are timezone-sensitive. Most platforms store timestamps in UTC. If the user provides a bare date like "2026-06-01", interpret it as the start of that day in UTC.
- When the user provides data via file or paste, the format may be inconsistent. Parse defensively: handle missing fields, varied delimiters, and mixed date formats gracefully.
- Different platforms use different terminology: GitHub has "Pull Requests", GitLab has "Merge Requests", Bitbucket has "Pull Requests", Azure DevOps has "Pull Requests". Normalize to the user's platform terminology in output.
