release-notes
Generates structured release notes from git history between two references (tags, commits, branches). Groups changes by type (features, fixes, docs, breaking), extracts PR references, and produces a publish-ready document.
Best use case
release-notes is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Generates structured release notes from git history between two references (tags, commits, branches). Groups changes by type (features, fixes, docs, breaking), extracts PR references, and produces a publish-ready document.
Teams using release-notes should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/release-notes/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How release-notes Compares
| Feature / Agent | release-notes | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Generates structured release notes from git history between two references (tags, commits, branches). Groups changes by type (features, fixes, docs, breaking), extracts PR references, and produces a publish-ready document.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Skill: Release Notes ## What This Skill Does Generates **publish-ready release notes** from git log. Parses conventional commits, groups by type, extracts PR numbers, highlights breaking changes, and produces a document ready for GitHub Releases, CHANGELOG, or team communication. ## When to Use - Before creating a GitHub Release - When the user says "what changed since last release?" - After merging a release branch - When updating CHANGELOG.md for a new version ## Execution Model - **Always**: the primary agent runs this skill directly. - **Token budget**: ~2-4k tokens. - **Output**: chat-based release notes + optional write to `CHANGELOG.md` or GitHub Release. ## Workflow ### Step 1: Determine Range Identify the git range to analyze: ```bash # Find latest tag git describe --tags --abbrev=0 # List recent tags git tag --sort=-version:refname | head -5 ``` Range options: - **Tag to HEAD**: `git log v1.0.0..HEAD` - **Between tags**: `git log v1.0.0..v1.1.0` - **Custom range**: user-specified ### Step 2: Collect Commits ```bash git log <range> --oneline --no-merges ``` For each commit, extract: - **Type**: from conventional commit prefix (feat, fix, docs, ci, chore) - **Scope**: from conventional commit scope (if present) - **Description**: the commit message - **PR number**: from merge commit or commit body ### Step 3: Group by Category | Category | Prefix | Description | |----------|--------|-------------| | Features | feat | New functionality | | Bug Fixes | fix | Fixed issues | | Documentation | docs | Documentation changes | | Maintenance | chore, ci, build | Internal improvements | | Breaking Changes | ! or BREAKING CHANGE | Require migration | ### Step 4: Detect Breaking Changes Scan for breaking change indicators: - `feat!:` or `fix!:` prefix - `BREAKING CHANGE:` in commit body - Removed exports or changed public APIs (if detectable from commits) ### Step 5: Generate Release Notes ```markdown # <version> — YYYY-MM-DD ## Breaking Changes - <description> (#PR) ## Features - <description> (#PR) - <description> (#PR) ## Bug Fixes - <description> (#PR) ## Documentation - <description> (#PR) ## Maintenance - <description> (#PR) --- **Full Changelog**: <compare-url> ``` ### Step 6: Publish Options Ask the user: 1. **GitHub Release**: `gh release create <tag> --notes-file /tmp/release-notes.md` 2. **CHANGELOG.md**: prepend to the changelog file 3. **Chat only**: just show the notes ## Rules 1. **Conventional commits are the source**: if the project doesn't use conventional commits, fall back to grouping by changed files (source vs tests vs docs). 2. **Breaking changes are prominent**: always list breaking changes first with clear migration guidance. 3. **PR references where possible**: link to PRs for traceability. 4. **Concise entries**: one line per change. Details belong in the PR, not in release notes. 5. **No built-in explore agent**: do NOT use the built-in `explore` subagent type.
Related Skills
release-it
Build production-ready systems with stability patterns: circuit breakers, bulkheads, timeouts, and retry logic. Use when the user mentions "production outage", "circuit breaker", "timeout strategy", "deployment pipeline", or "chaos engineering". Covers capacity planning, health checks, and anti-fragility patterns. For data systems, see ddia-systems. For system architecture, see system-design.
git:notes
Use when adding metadata to commits without changing history, tracking review status, test results, code quality annotations, or supplementing commit messages post-hoc - provides git notes commands and patterns for attaching non-invasive metadata to Git objects.
listennotes-automation
Automate Listennotes tasks via Rube MCP (Composio). Always search tools first for current schemas.
repo-story-time
Generate a comprehensive repository summary and narrative story from commit history
pyzotero
Interact with Zotero reference management libraries using the pyzotero Python client. Retrieve, create, update, and delete items, collections, tags, and attachments via the Zotero Web API v3. Use this skill when working with Zotero libraries programmatically, managing bibliographic references, exporting citations, searching library contents, uploading PDF attachments, or building research automation workflows that integrate with Zotero.
pydicom
Python library for working with DICOM (Digital Imaging and Communications in Medicine) files. Use this skill when reading, writing, or modifying medical imaging data in DICOM format, extracting pixel data from medical images (CT, MRI, X-ray, ultrasound), anonymizing DICOM files, working with DICOM metadata and tags, converting DICOM images to other formats, handling compressed DICOM data, or processing medical imaging datasets. Applies to tasks involving medical image analysis, PACS systems, radiology workflows, and healthcare imaging applications.
pr-ready
Prepares a feature branch for pull request. Runs all checks, generates PR description, verifies documentation is updated, creates changelog entry, and suggests labels.
perf-theory-gatherer
Use when generating performance hypotheses backed by git history and code evidence.
open-source-maintainer
End-to-end GitHub repository maintenance for open-source projects. Use when asked to triage issues, review PRs, analyze contributor activity, generate maintenance reports, or maintain a repository. Triggers include "triage", "maintain", "review PRs", "analyze issues", "repo maintenance", "what needs attention", "open source maintenance", or any request to understand and act on GitHub issues/PRs. Supports human-in-the-loop workflows with persistent memory across sessions.
my-pull-requests
List my pull requests in the current repository
multi-stage-dockerfile
Create optimized multi-stage Dockerfiles for any language or framework
mermaid-studio
Expert Mermaid diagram creation, validation, and rendering with dual-engine output (SVG/PNG/ASCII). Supports all 20+ diagram types including C4 architecture, AWS architecture-beta with service icons, flowcharts, sequence, ERD, state, class, mindmap, timeline, git graph, sankey, and more. Features code-to-diagram analysis, batch rendering, 15+ themes, and syntax validation. Use when users ask to create diagrams, visualize architecture, render mermaid files, generate ASCII diagrams, document system flows, model databases, draw AWS infrastructure, analyze code structure, or anything involving "mermaid", "diagram", "flowchart", "architecture diagram", "sequence diagram", "ERD", "C4", "ASCII diagram". Do NOT use for non-Mermaid image generation, data plotting with chart libraries, or general documentation writing.