release-notes-generator

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

<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.
• File import: Reads a local file containing PR/commit data in CSV, JSON, or Markdown format. Useful when the user has already exported data or when the repo is not API-accessible.
• Pasted content: The user pastes PR titles, commit messages, or a git log directly into the conversation. The skill parses and classifies from the raw text. </Definition - Supported Data Sources>

<Workflow - Generate Release Notes description="End-to-end release notes generation from data retrieval through formatted output." tools=[web_search, url_fetch, file_write, file_read, run_python, open_in_session_tab] triggers=["generate release notes", "write changelog", "summarize what shipped", "create release summary", "what merged since last release", "what's in this release"]

1. [Ask user] Gather any missing inputs: source, from_ref, to_ref, and format. If the user provided a vague range like "since last release," ask them to confirm the specific tag or offer to look up the most recent tag from the repository. If fails: If source, from_ref, or format is still missing, re-ask the user for the specific missing input before continuing.

2. [Decide] What type of source was provided?

   • Repository URL: Proceed to step 3.
   • File path: Proceed to step 4.
   • "paste" or inline data: Proceed to step 4 (parse from conversation context).

3. [Agent] Detect the platform from the URL pattern and fetch change data using the appropriate API:

   • github.com: Use the GitHub REST API (search/issues endpoint with is:pr+is:merged filters)
   • gitlab.com or self-hosted GitLab: Use the GitLab Merge Requests API
   • bitbucket.org: Use the Bitbucket Pull Requests API
   • dev.azure.com: Use the Azure DevOps Pull Requests API
   • Unrecognized: Inform the user the platform is not auto-detectable and ask them to export data to a file or paste it. For each change, collect: ID/number, title, labels/tags, author, merged date, and URL. Follow pagination to get all results in the range. If fails: If the API returns an authentication or access error, inform the user immediately and offer to accept a token, a file export, or pasted data per Rule 5.

4. [Decide] Is the source a file or pasted content?

   • File: Read the file. Detect format (CSV, JSON, Markdown, plain text git log). Parse into structured change entries.
   • Pasted: Parse the pasted content into structured change entries. Handle freeform text by extracting one entry per line or per commit message block. If parsing yields zero usable entries, inform the user and ask for clarification on the format.

5. [Decide] Evaluate the result count:

   • Zero changes: Confirm the range with the user per Rule 6. Ask if they want to widen the window.
   • More than 100 changes: Warn the user per Rule 11. Offer a category-count summary or full render.
   • 1 to 100 changes: Proceed to classification.

6. [Agent] Filter out excluded items: remove any with labels "skip-changelog", "no-release-notes", or "wontfix" per Rule 7. Remove bot-authored entries per Rule 10. Log how many were filtered. If fails: If filtering cannot complete, report the error and proceed with the unfiltered list, noting that excluded items may remain.

7. [Think] Classify each remaining change into exactly one Change Category. Check labels first (higher confidence), then fall back to title prefix conventions. If neither matches, assign to "Internal/Chores". Apply priority ordering per Rule 3 to resolve conflicts.

8. [Agent] Render the release notes in the requested format using run_python. Apply the appropriate template. Include: version/range header, date generated, breaking changes section (if any), then remaining categories in priority order, then a contributors list. Save the output to a file. If fails: If rendering or saving fails, report the error, retry once, and present the release notes inline if the retry fails.

9. [Ask user] Present the rendered release notes. Ask if they want adjustments: different grouping, exclude a category, add a summary paragraph at the top, or change the output format. If fails: If the user does not respond with a clear decision, re-present the notes and ask whether any adjustments are needed.

10. [Agent] Apply any requested edits, re-render, and save the final version. Open in the session tab for review. If fails: If the final version cannot be saved or opened, report the error, retry once, and present the release notes inline if the retry fails.

</Workflow - Generate Release Notes>

<Template - Markdown Release Notes>

# Release Notes: {{from_ref}} to {{to_ref}}

**Repository:** {{source}}
**Generated:** {{current_date}}
**Changes included:** {{total_count}} ({{filtered_count}} excluded)

{{#if breaking_changes}}
## Breaking Changes

{{#each breaking_changes}}
- {{title}} (#{{number}}) by @{{author}}
{{/each}}
{{/if}}

## Features

{{#each features}}
- {{title}} (#{{number}}) by @{{author}}
{{/each}}

## Bug Fixes

{{#each fixes}}
- {{title}} (#{{number}}) by @{{author}}
{{/each}}

## Other Changes

{{#each other}}
- {{title}} (#{{number}}) by @{{author}}
{{/each}}

## Contributors

{{contributors_list}}

Adapt per format: for chat_post, replace headers with bold+emoji; for platform_release, add compare URL and full changelog link; for wiki, wrap breaking changes in a warning panel.

</Template - Markdown Release Notes>

<Template - Chat Post Release Notes>

:rocket: *Release: {{from_ref}} to {{to_ref}}*
_{{repo_name}} | {{current_date}}_

{{#if breaking_changes}}
:warning: *Breaking Changes*
{{#each breaking_changes}}
- {{title}} (#{{number}}) by @{{author}}
{{/each}}

{{/if}}
:sparkles: *Features*
{{#each features}}
- {{title}} (#{{number}})
{{/each}}

:bug: *Bug Fixes*
{{#each fixes}}
- {{title}} (#{{number}})
{{/each}}

:busts_in_silhouette: *Contributors:* {{contributors_inline}}

Adjust emoji and section visibility based on which categories have entries. Omit empty sections entirely.

</Template - Chat Post Release Notes>