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:

git rev-parse --git-dir           # must be in a git repo
git status --porcelain            # warn if dirty
git branch --show-current         # show current branch

Checks:

Check	How	Severity
Git repo	`git rev-parse --git-dir`	Block — cannot proceed
CHANGELOG.md exists	Glob for changelog (case-insensitive)	Offer to create if missing
Has `[Unreleased]` section	Read CHANGELOG.md	Warn
Working tree clean	`git status --porcelain`	Warn (show dirty files)
On expected branch	`git branch --show-current`	Warn if not main/master/release
Tests pass	Detect and run test command	Warn (show failures)
Lint clean	Detect and run lint command	Warn (show issues)
Version consistency	Compare versions across package files	Warn (show mismatches)
Manifest versions sync	Compare `.claude-plugin/plugin.json` and `marketplace.json` versions	Warn (show mismatches)
Commits since last tag	`git log --oneline <range>`	Block if empty — nothing to release
Release cadence	Check date of last tag vs today	Warn if <7 days since last non-security release (see `references/release-cadence.md`)

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 tests and lint (still check git state and versions).

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

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 <last-tag>..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 <hash> 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<version>"

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<version>"

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<version>-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<version>-notes.md are committed to the repo. The CI pipeline (scripts/extract-release-notes.sh) reads them and passes them to GoReleaser via --release-notes.

Tell the user:

Release notes written to .agents/releases/YYYY-MM-DD-v<version>-notes.md
CI will use these as highlights on the GitHub Release page.

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 will handle: build, validate, publish, GitHub Release page
  (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<version>-audit.md:

# Release v<version> — Audit

**Date:** YYYY-MM-DD
**Previous:** v<previous-version>
**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](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [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<version>
Bad release notes → edit .agents/releases/*-notes.md before push

Universal Rules

Don't invent — only document what git log shows
No commit hashes in the final output
No author names in the final output
Concise — one sentence per bullet, technical but readable
Adapt, don't impose — match the project's existing style rather than forcing a particular format
User confirms — never write without showing the draft first
Local only — never push, publish, or trigger remote actions
Two audiences — CHANGELOG.md is for contributors (file paths, issue IDs, implementation detail). Release notes are for feed readers (plain English, user-visible impact, no insider jargon). Never copy-paste the changelog into the release notes.

Examples

Full Release Workflow

User says: /release 1.7.0

What happens:

Agent runs pre-flight checks (git status, tests, lint, versions)
Agent reads git history since last tag (v1.6.0..HEAD)
Agent classifies commits into Added/Changed/Fixed/Removed categories
Agent generates changelog entry in Keep a Changelog format
Agent detects version files (package.json, version.go) and proposes bumps
Agent shows draft changelog and version diffs to user for review
User approves. Agent writes CHANGELOG.md, updates version files
Agent creates release commit and annotated tag (v1.7.0)
Agent generates curated release notes (CI uses them for GitHub Release page)
Agent displays post-release guidance (push commands)

Result: Local release fully prepared: changelog updated, versions bumped, tag created, draft release ready.

Readiness Check Only

User says: /release --check

What happens:

Agent runs all pre-flight checks (git, tests, lint, versions, commits)
Agent outputs GO/NO-GO summary table with pass/fail/warn for each check
Agent stops without generating or writing anything

Result: Release readiness report only, no changes made.

Version Suggestion Mode

User says: /release (no version provided)

What happens:

Agent reads git history and classifies commits
Agent suggests version based on classification (major if breaking, minor if features, patch if fixes only)
Agent shows suggestion with reasoning: "Suggested version: 1.7.0 (minor). Reason: 3 new features added, no breaking changes."
Agent asks user to confirm or provide different version
Agent continues with user-selected version

Result: Suggested version based on commit analysis, user confirms or overrides.

Troubleshooting

Problem	Cause	Solution
"No commits since last tag" error	Working tree clean, no new commits	Commit pending changes or skip release (nothing to release)
Version mismatch warning	package.json shows 1.6.0, go shows 1.5.9	Manually sync versions before release, or choose one as source of truth
Tests fail during pre-flight	Breaking changes not caught earlier	Fix failing tests or use `--skip-checks` (not recommended)
Dirty working tree warning	Uncommitted changes present	Commit or stash changes before release for clean state
GitHub Release page has empty body	GoReleaser conflicts with existing draft release	CI workflow deletes existing releases before GoReleaser runs; do NOT `gh release create` locally