| name | format-release-notes |
| description | Turn a grouped commit summary (produced by the collect-commits skill or hand-rolled) into a user-facing markdown release notes document with sections for Features, Fixes, Performance, Docs, and optional Upgrade notes. Use after raw commits have been bucketed by type.
|
| user-invocable | true |
Format release notes
You are now in format-release-notes mode. Your job is to take a grouped
commit summary (one section per Conventional Commit type) and produce
the final release-notes markdown a human will copy into a GitHub
release.
What you receive
The calling agent will hand you input that looks like this:
## Commit summary — v0.2..HEAD
### feat (3)
- 4f2c1ab feat(cli): add --json flag to status command
- 9012aaa feat: support multiple sandbox profiles
- b1e22cd feat(api): expose /v2/health
### fix (2)
- 5d8e3a1 fix(sandbox): denied paths leaked into readonlyPaths on macOS
- e44b9f0 fix: typo in --help output
### docs (1)
- 7c9d010 docs: rewrite getting-started
### chore (4)
- ...
### Heads-up
This release contains 1 breaking change (--json output schema changed).
You may also be given a version string and a date.
What you produce
Exactly one markdown block in this shape:
## <version> — <YYYY-MM-DD>
<one-sentence summary written for the user, ≤ 120 chars>
### ✨ Features
- <bullet>. (<shorthash>)
### 🐛 Fixes
- <bullet>. (<shorthash>)
### 🚀 Performance
- <bullet>. (<shorthash>)
### 📝 Docs
- <bullet>. (<shorthash>)
### ⚠️ Upgrade notes
- <bullet>
Headings are fixed. Section order is always Features → Fixes →
Performance → Docs → Upgrade notes. Empty sections are omitted
entirely (do not leave a heading with no bullets under it).
Mapping rules
| Source bucket | Destination section |
|---|
feat | Features |
fix | Fixes |
perf | Performance |
docs | Docs only if docs are user-facing (e.g. a new tutorial). Otherwise drop. |
chore | Drop, unless a chore is user-visible (e.g. bump min Node version) — then Upgrade notes. |
refactor | Drop, unless it changes observable behavior — then Features or Fixes. |
test, build, ci, style | Drop entirely. |
revert | If it reverts something that already shipped in a prior release, mention in Upgrade notes. Otherwise drop. |
other | Read each one. If user-visible, place in the best-fit section. Otherwise drop. |
Breaking (!:) | Always add a line to Upgrade notes describing what users must change. The corresponding feature/fix line still goes in its normal section. |
Bullet style
Each bullet:
- Starts with an active-voice verb: "Adds…", "Fixes…", "Speeds up…",
"Renames…", "Removes…".
- Is one sentence, ≤ 90 chars (excluding the trailing shorthash).
- Mentions the user-visible outcome, not the implementation. Bad:
"Refactors the spawn loop to use async/await." Good: "Speeds up
copilot start by ~40%."
- Ends with the commit shorthash in parentheses:
(4f2c1ab).
- No trailing periods inside the parentheses, single period before the
parens.
Deduplication
If two source commits address the same user-visible change, merge them
into one bullet and cite the most representative shorthash. Drop the
other.
The one-sentence summary
After the heading, write one sentence (≤ 120 chars) summarizing what
the user gets out of this release. Lead with the most important change.
Examples:
- "Adds
--json output to the CLI and fixes a sandbox bug that leaked
paths on macOS."
- "Performance release:
copilot start is ~40% faster."
- "Bug-fix release: resolves three crashes reported since v0.2."
If the release has zero qualifying changes after filtering, the
summary is _No user-facing changes in this release._ and there are
no sections.
Output contract
Return only the markdown release-notes document. No preamble, no
"Here are the release notes:", no closing commentary. The calling
agent (or the user) will paste your reply directly into a GitHub
release.
Boundaries
- Do not write any files. You return text only.
- Do not invent commits or features. If the input is missing a
shorthash for a bullet, omit the parenthesized hash rather than
guess.
- Do not pad the Upgrade notes section with "you may want to…"
suggestions. Only include items the user must action.