Release

Release

Use this skill for repos that publish from GitHub Releases and want human-written notes instead of GitHub's generated summary.

Guardrails

• Prefer the repo's default branch from gh repo view; do not guess.
• Start from a clean working tree. If tracked files are dirty, stop and ask before continuing.
• If the current branch is not the default branch, stop and ask before switching.
• Fetch before planning: git fetch origin --tags.
• Fast-forward the default branch before editing: git pull --ff-only origin <default-branch>.
• Never force-push the default branch.
• Never use GitHub generated release notes for this workflow.
• Always create the release tag with a leading v, for example v0.1.0 or v0.2.0-beta.1.
• Always pin the release to the exact changelog commit SHA with gh release create --target <sha>.
• If origin/<default-branch> moves after planning or before pushing, stop and regenerate the release plan.
• For prereleases, use a semver prerelease tag that names the npm dist-tag you want, for example v0.2.0-beta.1 -> npm beta.
• For prereleases, create the GitHub release with --prerelease.
• Prefer leaving CHANGELOG.md untouched for prereleases unless the user explicitly wants beta entries there; that keeps later promotion to stable cleaner.

Helper Script

Use the bundled planner to gather release facts and raw note inputs:

python3 .agents/skills/release/scripts/release_plan.py --output-dir .local/release

Examples:

# Plan the next stable release.
python3 .agents/skills/release/scripts/release_plan.py --output-dir .local/release

# Plan the next beta prerelease for the upcoming stable line.
python3 .agents/skills/release/scripts/release_plan.py --channel beta --output-dir .local/release

# Promote an existing beta tag to a stable release from the same code base.
python3 .agents/skills/release/scripts/release_plan.py --promote-from v0.2.0-beta.2 --output-dir .local/release

It writes:

• .local/release/release-plan.json
• .local/release/release-plan.md

The planner:

• finds the latest published semver release
• counts first-parent commits on the default branch since that release
• filters leaked release-housekeeping commits such as changelog-only commits
• proposes the next stable tag, prerelease tag, or promotion target
• groups PR-backed changes separately from direct commits on main
• captures contributor mentions for PR-backed items
• when planning a prerelease, increments tags like v0.2.0-beta.1, v0.2.0-beta.2, and so on
• when planning a promotion, pins the plan to the exact prerelease tag commit instead of whatever is now at origin/<default-branch>

Approval Prompt

Before making any changelog edit, commit, push, tag, or release, show the user:

• the last release tag
• the raw and meaningful commit counts since that release
• the suggested new tag and why
• whether the change looks like a stable minor, a small emergency patch, a prerelease, or a prerelease promotion
• the exact commit SHA currently targeted by the release plan
• for prereleases, the npm dist-tag that will be used instead of latest

If the meaningful commit count is less than 3, explicitly warn that there are not many changes in this release and ask whether they still want to proceed.

Notes And Changelog Rules

• Do not copy PR titles verbatim into release notes.
• Rewrite each PR-backed item into a clearer user-facing bullet.
• For direct commits on main with no PR, use the commit subject and body as raw input and rewrite those too.
• Add the PR author mention on the same line for PR-backed entries.
• Keep the same substance in CHANGELOG.md and the GitHub release notes for stable releases.
• Prefer grouped sections such as Highlights, Fixes, Performance, Docs, and Internal when they fit the release.
• If CHANGELOG.md does not exist, create it with a # Changelog header.
• Insert the new release section at the top, directly under the file header if there is one.
• Use a heading in this shape:

## v0.1.0 - 2026-03-15

• If you make a dedicated changelog commit, use a subject like:

docs: add changelog for v0.1.0

• For prereleases, prefer writing only .local/release/release-notes.md and skipping a changelog commit unless the user explicitly wants prerelease changelog entries.
• For promotion from vX.Y.Z-beta.N to vX.Y.Z, either tag the same prerelease commit for exact code parity or add only changelog/release-note edits on top before creating the stable tag.