release-highlights

Stars14

Forks0

UpdatedJuly 15, 2026 at 17:48

Use when authoring or backfilling the "## Highlights" section of a GitHub release — the human-written summary that prepends the auto-generated notes. Covers when a release earns highlights, the fixed format (bold lead + breaking-change note, `###` subsections, PR-referenced bullets), and the prepend-in-place mechanics.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

mpyw

mpyw/suve

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	release-highlights
description	Use when authoring or backfilling the "## Highlights" section of a GitHub release — the human-written summary that prepends the auto-generated notes. Covers when a release earns highlights, the fixed format (bold lead + breaking-change note, `###` subsections, PR-referenced bullets), and the prepend-in-place mechanics.

Release highlights

Every tag's release body is auto-generated by .github/workflows/release.yml: NEW_NOTES (GitHub's generate-notes → ## What's Changed + Full Changelog) followed by the ## Downloads table (.github/templates/release-notes-downloads.md). Highlights are not part of that flow. A ## Highlights section is written by hand after the release exists and prepended to the auto-generated body — leave ## What's Changed and ## Downloads untouched. Precedent: v1.9.0 (TUI), v1.9.1 (npm + cloud shell), v1.9.2 (CloudShell fix).

When a release earns highlights

Write them when a reader skimming the release needs a "what changed and why it matters" that the raw PR list doesn't convey:

A headline feature or epic (v1.9.0 TUI, v1.9.1 npm distribution).
A distribution / install change users act on.
A notable fix, especially one that supersedes an earlier release's approach (v1.9.2 CloudShell — say so and reference the prior version).

A pure dependency-bump or internal-only patch does not need them.

Format (match it exactly)

## Highlights heading.
A bold one-sentence lead naming the release and its theme, followed by a breaking-change statement — almost always No breaking changes; existing CLI, TUI, and GUI behavior is unchanged. Only claim a break when there genuinely is one.
### subsections grouping related items (e.g. Distribution, Cloud shell support, TUI, Documentation, Quality, CI). Order most-to-least user-facing.
Bulleted items, each a bolded phrase then an em-dash explanation, ending with (#PR) references. Cite the PRs that delivered the item; a coverage/sweep item may cite a range (#831–#848).

Keep it accurate: only claim what the PRs actually did, and don't assert an epic is "complete" unless verified.

Mechanics

Reconstruct the full body (Highlights + existing) rather than editing in the GitHub UI — the auto-generated tail must survive verbatim.

gh release view vX.Y.Z --json body -q .body > body.md   # existing (## What's Changed … ## Downloads)
# write highlights.md, then:
cat highlights.md body.md > full.md
gh release edit vX.Y.Z --notes-file full.md

immutable: true on a release refers to its assets, not the body — the notes stay editable, and re-running gh release edit is safe and reversible.

Editing a public release page is outward-facing; draft the Highlights text and confirm with the maintainer before publishing unless already told to proceed.

More from this repository

same repository

docs-site-pages

mpyw/suve

Use when restructuring the README or the GitHub Pages site generated from it — the left-nav/left-pane, section reorg, or per-provider command docs. Covers the build-docs-site.py split + literate-nav SUMMARY pipeline, its HTML-comment directives and site-only transforms (nav-group, site:skip, hero <h1>, asset ../ prefix, DOC_NAV grouping), the python-markdown gotchas GitHub hides, and the `mise docs-build` strict gate.

2026-07-1614

refresh-demo-gifs

mpyw/suve

Use when re-recording the CLI, TUI, or GUI demo GIFs after a UI change or a user-visible output change. Covers the record scripts, robust Playwright selectors, output-drift triggers, frame verification, and Git LFS.

2026-07-1314

collection-idioms

mpyw/suve

Load when writing or reviewing Go that builds or transforms slices/maps. Prefer samber/lo, samber/lo/it, and stdlib slices/maps callback & iterator utilities over hand-rolled make + range + append; keep an explicit loop only where side effects or control flow are genuinely complex.

2026-07-1214

suve-cli-map

mpyw/suve

Load when you need the per-provider capability, versioning, and alias matrix for suve's CLI without reading the full docs/{aws,azure,gcloud}.md option tables. A one-page orientation; link out for per-command detail.

2026-07-1214

provider-seam-invariants

mpyw/suve

Load when adding or modifying a provider adapter, or when touching internal/provider/** or internal/domain/**. Captures the invariants that keep the provider-neutral seam honest: the neutral domain model, opaque version refs, the typed write/delete option pattern, interface segregation, and SDK confinement.

2026-07-1214

provider-selection-and-registry

mpyw/suve

Load when wiring a top-level command group, adding a cloud, or touching internal/provider/registry.go, internal/provider/detect/, or internal/cli/commands/internal/client.go. Explains how a provider is selected (explicit groups plus env-detected flat aliases), how the registry composes backends, how each provider's scope is built, and the SDK-confinement boundary.

2026-07-1214

name	release-highlights
description	Use when authoring or backfilling the "## Highlights" section of a GitHub release — the human-written summary that prepends the auto-generated notes. Covers when a release earns highlights, the fixed format (bold lead + breaking-change note, `###` subsections, PR-referenced bullets), and the prepend-in-place mechanics.

Release highlights

When a release earns highlights

Write them when a reader skimming the release needs a "what changed and why it matters" that the raw PR list doesn't convey:

A headline feature or epic (v1.9.0 TUI, v1.9.1 npm distribution).
A distribution / install change users act on.
A notable fix, especially one that supersedes an earlier release's approach (v1.9.2 CloudShell — say so and reference the prior version).

A pure dependency-bump or internal-only patch does not need them.

Format (match it exactly)

## Highlights heading.
A bold one-sentence lead naming the release and its theme, followed by a breaking-change statement — almost always No breaking changes; existing CLI, TUI, and GUI behavior is unchanged. Only claim a break when there genuinely is one.
### subsections grouping related items (e.g. Distribution, Cloud shell support, TUI, Documentation, Quality, CI). Order most-to-least user-facing.
Bulleted items, each a bolded phrase then an em-dash explanation, ending with (#PR) references. Cite the PRs that delivered the item; a coverage/sweep item may cite a range (#831–#848).

Keep it accurate: only claim what the PRs actually did, and don't assert an epic is "complete" unless verified.

Mechanics

Reconstruct the full body (Highlights + existing) rather than editing in the GitHub UI — the auto-generated tail must survive verbatim.

gh release view vX.Y.Z --json body -q .body > body.md   # existing (## What's Changed … ## Downloads)
# write highlights.md, then:
cat highlights.md body.md > full.md
gh release edit vX.Y.Z --notes-file full.md

immutable: true on a release refers to its assets, not the body — the notes stay editable, and re-running gh release edit is safe and reversible.

Editing a public release page is outward-facing; draft the Highlights text and confirm with the maintainer before publishing unless already told to proceed.