Release Skill Purpose: Take a project from "code is ready" to "tagged and ready to push." Pre-flight validation, changelog from git history, version bumps across package files, release commit, annotated tag, and curated release notes. Everything is local and reversible. Publishing (including the GitHub Release page) is CI's job. Quick Start /release 1.7 .0
full release: changelog + bump + commit + tag
/release 1.7 .0 --dry-run
show what would happen, change nothing
/release --check
readiness validation only (GO/NO-GO)
/release
suggest version from commit analysis
Arguments Argument Required Description version No Semver string (e.g., 1.7.0 ). If omitted, suggest based on commit analysis --check No Readiness validation only — don't generate or write anything --dry-run No Show generated changelog + version bumps without writing --skip-checks No Skip pre-flight validation (tests, lint) --changelog-only No Only update CHANGELOG.md — no version bumps, no commit, no tag Modes Default: Full Release /release [version] — the complete local release workflow. Steps: pre-flight → changelog → release notes → version bump → user review → write → release commit → tag → guidance. Check Mode /release --check — standalone readiness validation. Runs all pre-flight checks and reports GO/NO-GO. Useful before starting the release, in CI as a gate, or composed with /vibe . Does not generate or write anything. Changelog Only /release 1.7.0 --changelog-only — just update CHANGELOG.md. Generates the changelog entry and writes it. No version bumps, no commit, no tag. Workflow Step 1: Pre-flight Run these checks before anything else: ./scripts/ci-local-release.sh
mandatory local CI parity gate (blocking)
git rev-parse --git-dir
must be in a git repo
git status --porcelain
warn if dirty
git branch --show-current
show current branch
/release
MUST run the repo-root
ci-local-release.sh
gate first. If it fails, stop the release workflow and report the failing checks.
The local CI gate writes publishable artifacts to
.agents/releases/local-ci/
/dev/null || echo 0 ) if [ " $high_count " -gt 0 ] ; then echo "[WARN] $high_count unconsumed high-severity item(s) in .agents/rpi/next-work.jsonl" echo " These carry-forward findings have not been addressed. Review before releasing." echo " Run: jq -s '[.[] | select(.consumed==false) | .items[] | select(.severity== \" high \" )]' .agents/rpi/next-work.jsonl" fi fi This is a soft WARN — it does not block the release. It surfaces carry-forward findings from prior retro/post-mortem sessions so the release engineer can make an informed decision. Test/lint detection: File Test Command Lint Command go.mod go test ./... golangci-lint run (if installed) package.json npm test npm run lint (if script exists) pyproject.toml pytest ruff check . (if installed) Cargo.toml cargo test cargo clippy (if installed) Makefile with test: make test make lint (if target exists) If --skip-checks is passed, skip ad-hoc test/lint detection only. It does not skip the repo-root ci-local-release.sh gate. In --check mode, run all checks and output a summary table: Release Readiness: NO-GO [PASS] Git repo [PASS] CHANGELOG.md exists [PASS] Working tree clean [WARN] Branch: feature/foo (expected main) [FAIL] Tests: 2 failures in auth_test.go [PASS] Lint clean [PASS] Version consistency (1.6.0 in all 2 files) [PASS] 14 commits since v1.6.0 [WARN] 2 unconsumed high-severity item(s) in .agents/rpi/next-work.jsonl In --check mode, stop here. In default mode, continue (warnings don't block). Step 2: Determine range Find the last release tag: git tag --sort = -version:refname -l 'v' | head -1 If no v tags exist, use the first commit: git rev-list --max-parents=0 HEAD The range is
..HEAD If range is empty (no new commits), stop and tell the user Step 3: Read git history Gather commit data for classification: git log --oneline --no-merges < range git log --format = "%H %s" --no-merges < range
git diff --stat < range
Use --oneline for the summary view and full hashes for detail lookups when a commit message is ambiguous. Step 4: Classify and group Classify each commit into one of four categories: Category Signal Added New features, new files, "add", "create", "implement", "introduce", feat Changed Modifications, updates, refactors, "update", "refactor", "rename", "migrate" Fixed Bug fixes, corrections, "fix", "correct", "resolve", "patch" Removed Deletions, "remove", "delete", "drop", "deprecate" Grouping rules: Group related commits that share a component prefix (e.g., auth: , api: , feat(users) ) Combine grouped commits into a single bullet with a merged description Match the existing CHANGELOG style — read the most recent versioned entry and replicate its bullet format, separator style, and heading structure If a commit message is ambiguous, read the diff with git show --stat
to clarify Key rules: Don't invent — only document what git log shows Omit empty sections — don't include
Removed
if nothing was removed Commits, not diffs — classify from commit messages; read diffs only when ambiguous Merge-commit subjects are noise — already filtered by --no-merges Step 5: Suggest version If no version was provided, suggest one based on the commit classification: Condition Suggestion Any commit contains "BREAKING", "breaking change", or !: (conventional commits) Major bump Any commits classified as Added (new features) Minor bump Only Fixed/Changed commits Patch bump Show the suggestion with reasoning: Suggested version: 1.7.0 (minor) Reason: 3 new features added, no breaking changes Current version: 1.6.0 (from package.json, go tags) Use AskUserQuestion to confirm or let the user provide a different version. Step 6: Generate changelog entry Produce a markdown block in Keep a Changelog format:
[X.Y.Z] - YYYY-MM-DD
Added
description of new feature
Changed
description of change
Fixed
description of fix Use today's date in YYYY-MM-DD format. Style adaptation: Read the existing CHANGELOG entries and match their conventions: Bullet format (plain text vs bold names vs backtick names) Separator style (em-dash — , hyphen - , colon : ) Grouping patterns (flat list vs sub-sections) Level of detail (terse vs verbose) If no existing entries to reference (first release), use plain Keep a Changelog defaults. Step 7: Detect and offer version bumps Scan for files containing version strings: File Pattern Example package.json "version": "X.Y.Z" "version": "1.6.0" pyproject.toml version = "X.Y.Z" version = "1.6.0" Cargo.toml version = "X.Y.Z" version = "1.6.0" *.go const Version = "X.Y.Z" or var version = "X.Y.Z" const Version = "1.6.0" version.txt Plain version string 1.6.0 VERSION Plain version string 1.6.0 .goreleaser.yml Version from ldflags (show, don't modify — goreleaser reads from git tags) — Show what was found: Version strings detected: package.json: "version": "1.6.0" → "1.7.0" src/version.go: const Version = "1.6.0" → "1.7.0" .goreleaser.yml: (reads from git tag — no change needed) Use AskUserQuestion: "Update these version strings?" — "Yes, update all" / "Let me choose" / "Skip version bumps" Step 8: User review Present everything that will change: The generated changelog entry (fenced markdown block) The version bumps (file-by-file diff preview) What will happen: "Will write CHANGELOG.md, update 2 version files, create release commit, create tag v1.7.0" If --dry-run was passed, stop here. Use AskUserQuestion: "Proceed with this release?" Options: "Yes, do it" / "Let me edit the changelog first" / "Abort" Step 9: Write changes After user confirms: Update CHANGELOG.md: Find the
[Unreleased]
line Find where the unreleased section ends (next
[
line or EOF) Replace with: fresh empty
[Unreleased]
- blank line + versioned entry
Update version files
(if user accepted bumps)
Step 10: Release commit
Stage and commit all release changes together:
git
add
CHANGELOG.md
<
version-files
..
.
git commit -m "Release v
" The commit message is intentionally simple. The changelog has the details. Step 11: Tag Create an annotated tag: git tag -a v < version -m "Release v
" Step 12: Generate release notes Read references/release-notes.md for the full release notes format, quality bar, condensing rules, and examples. Key points: Release notes are not the changelog — they're user-facing, plain-English, no jargon Structure: Highlights → What's New → All Changes (condensed) → link to full CHANGELOG Write to .agents/releases/YYYY-MM-DD-v -notes.md Show to the user as part of Step 8 review Step 13: GitHub Release (CI handles this) Do NOT create a draft GitHub Release locally. GoReleaser in CI is the sole release creator. A local gh release create --draft conflicts with GoReleaser and results in an empty release body. The curated release notes at .agents/releases/YYYY-MM-DD-v -notes.md are committed to the repo. The CI pipeline ( extract-release-notes.sh at repo root) reads them and passes them to GoReleaser via --release-notes . CI also publishes security artifacts to the GitHub Release assets: sbom-cyclonedx-go-mod.json security-gate-summary.json Tell the user: Release notes written to .agents/releases/YYYY-MM-DD-v -notes.md CI will use these as highlights on the GitHub Release page. CI will attach SBOM and security scan report assets. Step 14: Post-release guidance Show the user what to do next: Release v1.7.0 prepared locally. Next steps: git push origin main --tags # push commit + tag CI publisher will handle: release publish, GitHub Release page, SBOM/security assets, provenance (detected: .github/workflows/release.yml, .goreleaser.yml) Curated release notes: .agents/releases/YYYY-MM-DD-v1.7.0-notes.md If no CI detected: Next steps: git push origin main --tags # push commit + tag gh release create v1.7.0 --title "v1.7.0" --notes-file .agents/releases/YYYY-MM-DD-v1.7.0-notes.md No release CI detected. Consider adding a workflow for automated publishing. Step 15: Audit trail Write an internal release record (separate from the public release notes written in Step 12): mkdir -p .agents/releases Write to .agents/releases/YYYY-MM-DD-v -audit.md :
Release v
** Commits: ** N commits in range
Version Bumps < files updated
Pre-flight Results < check summary table
This is an internal record for the knowledge flywheel. It does NOT go on the GitHub Release page — that's the -notes.md file from Step 12. Two files, two audiences: File Audience Contains -notes.md GitHub feed readers Highlights, What's New, All Changes -audit.md Internal/flywheel Version bumps, pre-flight results New Changelog Template When no CHANGELOG.md exists and the user accepts creation, write:
Changelog All notable changes to this project will be documented in this file. The format is based on Keep a Changelog , and this project adheres to Semantic Versioning .
[Unreleased]
Then proceed with the normal workflow to populate the first versioned entry.
Boundaries
What this skill does
Pre-flight validation (tests, lint, clean tree, versions, branch)
Changelog generation from git history
Semver suggestion from commit classification
Version string bumps in package files
Release commit + annotated tag
Release notes (highlights + changelog) for GitHub Release page
Curated release notes for CI to publish on GitHub Release page
Post-release guidance
Audit trail
What this skill does NOT do
No publishing
— no
npm publish
,
cargo publish
,
twine upload
. CI handles this.
No building
— no
go build
,
npm pack
,
docker build
. CI handles this.
No pushing
— no
git push
, no
git push --tags
. The user decides when to push.
No CI triggering
— the tag push (done by the user) triggers CI.
No monorepo multi-version
— one version, one changelog, one tag. Scope for v2.
Everything this skill does is local and reversible:
Bad changelog → edit the file
Wrong version bump →
git reset HEAD~1
Bad tag →
git tag -d v