| name | release |
| description | Drafts style-compliant release notes by summarizing the pull requests merged since the previous release. Infers and recommends the release type (major, minor, or patch) for the user to confirm, then produces a numbered list of the most impactful changes. Includes a sibling-library compatibility statement for cross-dependent library sets only. Use when preparing a release, drafting release notes, or when the user invokes /release. |
| user-invocable | true |
Release
Drafts style-compliant release notes summarizing the pull requests merged since the previous release.
Scope
Covers:
- Identifying the previous release and the pull requests merged since then
- Inferring and recommending the release type (major, minor, patch) for user confirmation
- Drafting release notes with a numbered list of the most impactful changes
- Including a sibling-library compatibility statement for cross-dependent library sets
Does not cover:
- Creating tags, GitHub releases, or publishing (the user does this)
- The
## What's Changed and **Full Changelog** sections (GitHub generates these automatically on release)
- Committing, pushing, or opening pull requests (see
/commit and /pr)
Workflow
You MUST follow these steps exactly when this skill is invoked.
Step 1: Gather context
Run the following git commands using the Bash tool:
- Identify the previous release tag with
git tag --sort=-v:refname (most recent first) or git describe --tags --abbrev=0.
- List the pull requests merged since that tag with
git log <previous-tag>..HEAD --merges --format='%h %s%n%b'. The
Merge pull request #N from ... subject line names only the number and source branch, while the pull request title
and description live in the commit body, so you MUST read the body (not --oneline) to draft the notes.
- Review the aggregate change scope with
git diff <previous-tag>..HEAD --stat.
If --merges returns few or no results relative to the git diff --stat scope, the repository likely uses squash- or
rebase-merged pull requests or direct commits to the default branch, which produce no merge commit. Enumerate from git log <previous-tag>..HEAD --oneline --no-merges instead and reconcile both so no merged work is silently dropped.
If the repository has no prior release tag, summarize the full history (git log --merges --format='%h %s%n%b') and
note that this is the first release.
Step 2: Determine the dependency model
Determine whether the project is an independent library or part of a unified, cross-dependent library set:
- Cross-dependent set: the project ships as one of a unified set of sibling libraries released and versioned
together, so the release notes MUST include a compatibility statement (Step 4).
- Independent library: the project (like the ataraxis libraries) has no enforced cross-dependency web, so the
release notes MUST NOT include a compatibility statement.
Step 3: Infer and recommend the release type
Infer the release type from the change set and recommend it to the user. You MUST ask the user to confirm the type
before finalizing the notes. The user decides the type, so never decide it unilaterally.
For C++ PlatformIO libraries the release version is single-sourced from library.json rather than pyproject.toml, which
is where Python projects hold it. See /platformio-config.
| Type | Use case |
|---|
| Major | Breaking API changes, removals, re-licensing, or migrations requiring downstream updates |
| Minor | New, backward-compatible features or capabilities |
| Patch | Bug fixes and minor corrections with no new features |
Step 4: Resolve the compatibility statement (cross-dependent sets only)
For cross-dependent releases, the compatibility statement names the sibling-library versions this release is designed to
work with. You cannot reliably infer these, so ask the user to confirm the compatible sibling-library versions and
include them verbatim. For independent libraries, skip this step entirely.
Step 5: Draft the release notes
Produce the release notes following the format below. Present the draft to the user. The user creates the tag and GitHub
release manually.
Format
### {Major|Minor|Patch} Release
[cross-dependent sets only] This release is designed to work with <sibling-library> vN, <sibling-library> vM, ...
**Major Changes:**
1. <Most impactful change, past tense, descriptive sentence.>
2. <Next change.>
Rules
- The first line is
### {type} Release using the user-confirmed type.
- For cross-dependent releases, follow the header with a single compatibility sentence naming the confirmed
sibling-library versions. Omit this line entirely for independent libraries.
**Major Changes:** introduces a numbered list (1., 2., …) of the most impactful changes, ordered from most to
least impactful.- Each item is a complete, descriptive sentence in past tense (see the verb set in
/commit) ending with a period.
- Each item occupies one line, under the line-break rule
/commit defines. GitHub soft-wraps the release body, so a
hand-wrapped item renders as a rigid block.
- Condense many pull requests into a few impactful themes. Do NOT list every pull request.
- Do NOT include a
## What's Changed section or a **Full Changelog** line. GitHub generates these automatically when
the release is published.
Prose punctuation and positive description
Prose uses only the full stop and the comma to separate clauses. Do not use a semicolon or an em-dash (--, —, or
–) as a separator, and use a colon only where it is lexically appropriate. A single hyphen stays available as a list
marker, in tables, and in compound words. A -- naming a CLI flag or an argument separator, like any token inside a
code span, is not a clause separator and is left as written. State what the subject does and what is currently true. Do
not frame it by what it is not or what it used to be, and keep a "not Y" contrast only when it is load-bearing because
it corrects a counter-intuitive assumption, giving its reason.
Examples
Good (independent library, no compatibility statement):
### Major Release
**Major Changes:**
1. Re-licensed the library to Apache 2.0.
2. Added MCP assets and a companion plugin that enables AI agent interfacing with all library components.
3. Added a log processing (data extraction) pipeline.
Good (cross-dependent set, compatibility statement included):
### Minor Release
This release is designed to work with `acquisition` v5, `behavior` v3, and `analysis` v1.
**Major Changes:**
1. Added shared project and animal data-hierarchy assets for walking the project tree without SessionData.
2. Introduced the data root as a fourth persistent host setting, with MCP tools and CLI commands to manage it.
Content rules
The release notes follow the content rules /commit defines for commit messages. They describe ONLY the changes
themselves, and /commit carries the forbidden-content list that applies here verbatim.
What and why, not how: Each item states what the release changed and why, not how, and is specific and
descriptive rather than vague like "Updated various modules".
Sentence length: Every sentence in a release note item stays under 40 words, broken at a natural clause boundary or
split into two numbered items when it runs longer.
Typo-free and grammatical: The release notes must be free of typos and grammatical errors, with every symbol name,
file name, and version string verified against the diff or tag output rather than recalled from memory.
Related skills
| Skill | Relationship |
|---|
/commit | Provides the past tense verb set and the content rules reused here |
/pr | Drafts the per-branch pull request summaries that releases aggregate |
/explore-codebase | Provides project context that helps write accurate summaries |
/platformio-config | Owns library.json whose version field is the C++ library release version |
/pyproject-style | Owns pyproject.toml whose version field is the Python release version |
Proactive behavior
When the user signals that a release is imminent (a version bump, "preparing a release", or similar), proactively offer
to draft release notes. For example: "Would you like me to draft release notes for this version?"
Do NOT create tags or GitHub releases. Present the drafted notes for the user to use manually.
Verification checklist
You MUST verify the release notes against this checklist before presenting them to the user.
Release Notes Compliance:
- [ ] First line is `### {Major|Minor|Patch} Release` with the user-confirmed type
- [ ] Release type was recommended AND confirmed by the user
- [ ] Compatibility statement included for cross-dependent releases, omitted for independent libraries
- [ ] Sibling-library versions confirmed by the user (cross-dependent sets only)
- [ ] `**Major Changes:**` numbered list ordered from most to least impactful
- [ ] Each item is past tense and ends with a period
- [ ] Each item occupies one line, with no hand-wrapped continuation
- [ ] Each item describes *what* changed and *why*, not *how*, and is specific rather than vague (not "Updated
various modules")
- [ ] Prose separators are full stops and commas only, no semicolons or em-dashes (colons, hyphen bullets, and code
syntax exempt)
- [ ] Prose states what the release does, not what it is not or used to be (contrast only when load-bearing)
- [ ] Every sentence in the drafted text stays under 40 words
- [ ] Free of typos and grammar errors, with every symbol name, file name, and version string verified against the diff
or tag output rather than recalled from memory
- [ ] Condenses many pull requests into a few impactful themes (does not list every pull request)
- [ ] Does NOT include `## What's Changed` or `**Full Changelog**`
- [ ] Enumerated changes since the previous release tag, reconciling merge and squash/rebase history against the
`--stat` scope
- [ ] Contains NO authorship details, co-author tags, or attribution
- [ ] Contains NO references to tools or AI unless explicitly requested by the user
- [ ] Contains ONLY information about the changes themselves
- [ ] Did NOT create a tag or GitHub release
