sunwood-ai-labs/gh-release-notes-skill/gh-release-notes-skill

GitHub Release Notes

Overview

Create release notes from repository evidence, not commit subjects alone.

Use this skill to:

• draft release notes before publishing a tag
• rewrite thin or inaccurate existing GitHub release bodies
• create or update GitHub releases with gh release create or gh release edit
• handle first releases where there is no previous tag
• draft docs-backed article pages from the same release evidence when the user wants a blog or announcement post
• create a companion walkthrough article by default when publishing a release from a repository that already has a docs surface
• derive a new versioned release header SVG when the repository already has an earlier release header asset
• derive a new versioned release header SVG by default when the repository already ships suitable reusable SVG branding such as assets/icon.svg, assets/logo.svg, or a branded assets/social-card.svg, the release would benefit from a hero image, and there is no earlier versioned release header asset yet
• validate every candidate SVG before reusing existing header art or deriving new release header assets from repo branding
• mirror release notes into repository docs by default when the target repository already publishes docs
• keep release collateral, README, and primary operator docs aligned with code-backed shipped behavior
• require a release QA inventory artifact and validate it before closing the task
• keep release notes grounded in actual shipped behavior

Prerequisites

• access to a local clone of the target repository
• git available in the shell
• gh installed and authenticated if publishing is requested
• permission to inspect diffs, tags, and release state

Default Workflow

1. Read the target repository README if one exists and inspect the tag or release state.

• Run gh auth status if the user expects you to publish or edit a GitHub release.
• Fetch tags first when the local clone may be stale.

1. Determine the comparison range.

• If the target tag has a previous tag, compare from that previous tag to the target tag.
• If there is no previous tag, treat the release as an initial release and cover the full shipped history explicitly.
• Use an explicit base tag when the release line is non-linear or when backfilled tags make auto-detection ambiguous.

1. Run the bundled collector first.

• powershell -ExecutionPolicy Bypass -File ./scripts/collect-release-context.ps1 -Tag v0.1.0
• If the tag exists only on GitHub and not in the local clone yet, fetch tags first or use -Target <commit-or-branch>.
• Use -BaseTag <tag> to override the automatically detected previous tag.
• Read the output, then inspect the actual diffs for the high-impact files and commits.

1. Review implementation diffs, not just summaries.

• Read the changed file list and diff stats first.
• Always inspect new or heavily changed scripts, workflows, fixtures, docs, and user-facing assets.
• Search for existing release header assets such as assets/release-header-v0.2.0.svg, docs/public/.../release-header-v0.2.0.svg, or similar versioned SVGs before deciding whether to create a new header image.
• If there is no versioned release header asset yet, search for reusable SVG branding such as assets/icon.svg, assets/logo.svg, assets/social-card.svg, or equivalent repo branding and treat that as the default seed for a new release-header-v*.svg only when the branding is suitable for a release hero image.
• Validate every candidate SVG you might reuse with powershell -ExecutionPolicy Bypass -File ./scripts/verify-svg-assets.ps1 -RepoPath . -Path <svg-paths> before treating it as a reusable seed. Broken XML, missing <svg> roots, unresolved internal id references, or SVGs without scalable dimensions are not valid release-header inputs.
• Use git show on major commits and touched files until you can name concrete capabilities added.
• For implementation-sensitive claims such as model selection, retry/backoff, routing, defaults, environment variables, telemetry surfaces, or command behavior, inspect the actual code paths and tests that implement them.
• When those claims depend on configuration or runtime wiring, read the config readers, command entrypoints, runtime call sites, and operator-visible output formatting instead of relying on one file in isolation.
• If a behavior applies only to one command, service, embed, or deployment mode, keep the wording scoped to that exact surface instead of generalizing it.

1. Draft the requested output in the user's requested language.

• Open with release scope and whether it is an initial release.
• Group the material by user-visible capabilities and implementation areas, not by raw commit count.
• Mention validation only if you actually ran it.
• Use references/release-note-template.md when you want a release-note scaffold.
• If the user wants GitHub release notes, draft a publishable release body.
• If the repository has a docs surface and the user is publishing a release, create both docs-backed release notes and a companion walkthrough article by default unless the user explicitly asks for release-notes-only.
• If the user wants article output, draft docs-backed article pages instead of a detached local draft whenever the repository has a docs surface.
• Do not stop at "I will draft the article next" when article output is in scope. Create the article pages in the same task unless the user explicitly paused the work.
• Do not treat the release-note page as a substitute for the companion walkthrough article when the repository already publishes docs and the release is being published.

1. If you are drafting article output, or if you are publishing a release in a repository with a docs surface, inspect the repository docs surface and place the article in docs by default.

• When the repository already has bilingual English and Japanese docs, create both docs/guide/articles/<slug>.md and docs/ja/guide/articles/<slug>.md.
• When the repository has only one docs locale, use the matching existing docs structure.
• Keep the body free of Zenn or Qiita frontmatter.
• Use a structure such as short introduction, key points, main features, workflow impact, validation, and links.
• Reuse public screenshots, animated assets, and docs links when they help readers understand the release.
• Update article index pages such as docs/guide/articles.md and docs/ja/guide/articles.md when they already exist.
• Add a related article link from release summary pages when the docs structure already has release pages.

1. If the repository already has versioned release header SVG assets, create a new header image for the target version and reuse it everywhere the release appears.

• Use the nearest existing asset, such as assets/release-header-v0.2.0.svg, as the visual base instead of inventing a totally new style.
• Update the version text and adjust the header copy or visual emphasis to match the current release scope.
• Save the new asset using the repository's established naming and folder pattern.
• When the seed asset is outside the published docs asset surface, also create or mirror a published copy so docs pages and GitHub releases can reference it.
• Place the header image near the top of the GitHub release body, the docs release page, and any docs article page created for the same release.
• In the GitHub release body, use a published URL such as the docs site URL or a raw GitHub asset URL rather than a local relative path.
• If the repository does not already have versioned release header art but does have reusable SVG branding such as assets/icon.svg, assets/logo.svg, or a branded assets/social-card.svg, treat header generation as the default behavior only when the release would benefit from a hero image, the SVG is suitable for reuse, and the user did not narrow scope away from visual collateral.
• Run scripts/verify-svg-assets.ps1 on the source SVGs before reuse, then run it again on the generated release-header-v*.svg before you publish or reference that asset anywhere.
• Derive the new release-header-v*.svg from that existing SVG branding so the release inherits the repo's established visual language rather than shipping without a hero image.
• If the available SVG is icon-only, too low-detail, stylistically mismatched, invalid, broken, or otherwise unsuitable for a release hero image, explicitly skip header generation or mark it as review-required instead of forcing a weak result.

1. Inspect the repository docs surface before publishing and treat docs-backed release notes plus a companion docs-backed walkthrough article as the default path.

• Reuse the existing docs framework, locale structure, and navigation style instead of inventing a parallel format.
• Create or update the matching docs page in every language already supported by the repository, unless the user narrowed the request.
• Treat the release-note page and companion walkthrough article as release collateral, not as an automatic substitute for steady-state docs such as README, overview, CLI, setup, deployment, smoke-test, or operator runbooks.
• Extract the operator-facing claims introduced or emphasized by the release docs, then review the primary steady-state docs to decide which of those surfaces must also be updated.
• When the release changes operator expectations, configuration, routing, retry behavior, outputs, or verification flow, update the matching steady-state docs in the same task instead of leaving the detail only in release collateral.
• Update stale "latest release" links, overview pointers, and docs navigation when the repository exposes them.
• If the GitHub release body should link into docs, commit and push the docs changes first, wait for docs deployment, and only then publish or edit the final GitHub release body so it can point at live URLs.
• Prefer badge-style links at the top of the GitHub release body so readers can jump to the docs pages.
• In the GitHub release body, render top docs links as shields.io badge images inside a centered HTML paragraph, not as plain Markdown links or a punctuation-separated link list.
• Keep the badge paragraph centered with <p align="center">...</p> and include one badge per important destination such as English docs, Japanese docs, walkthrough, and Japanese walkthrough when those pages exist.
• Prefer linking both the docs-backed release notes page and the companion walkthrough article from the GitHub release body when both exist.
• Skip the companion article only when the repository clearly has no docs publishing surface or the user explicitly asks for release-notes-only.

1. Materialize the QA inventory as a file in the target repository before calling the work complete.

• Copy references/release-qa-inventory-template.md into the standard task artifact path tmp/release-qa-<tag>.md in the target repository, for example tmp/release-qa-v1.2.3.md.
• Fill in the claim matrix, steady-state docs review table, and QA inventory rows with concrete evidence from the current task.
• Validate the filled artifact with scripts/verify-release-qa-inventory.ps1 by passing the target repo path and tag, for example powershell -ExecutionPolicy Bypass -File <skill-root>\scripts\verify-release-qa-inventory.ps1 -RepoPath . -Tag v1.2.3.
• Do not close the task while the validator reports any failure.

1. Publish or update the release with gh when GitHub publication is part of the task.

• Ensure every docs page and asset referenced by the release body is already committed before creating the release tag.
• Create and push the release tag only after t