release

name	release
description	Analyze changes, determine semantic version bump, build executables, and cut a GitHub release with Claude-written minimalist notes.
allowed-tools	Read, Bash, Grep, Glob

Release

Automatically analyze changes, determine semantic versioning, build binaries, and create GitHub releases with custom Claude-written release notes.

Overview

This skill automates the complete release process:

1. Analyze git commits since last tag
2. Determine semantic version bump (major.minor.patch)
3. Build executables for all platforms using make build-all
4. Create git tag with new version
5. Generate minimalist release notes (always written by Claude)
6. Write release notes to temporary file
7. Create GitHub release using make release RELEASE_NOTES=/tmp/release-notes.md

The Releaser Agent

The releaser agent writes minimalist, actionable release notes that:

• Focus on user impact, not implementation details
• Use clear, concise language
• Group related changes logically
• Avoid redundancy and noise
• Skip obvious or trivial changes

Tone: Professional, direct, minimal. Think release notes from tools like ripgrep or fd.

Semantic Versioning Rules

Analyze commits since the last tag to determine the version bump:

MAJOR (x.0.0) - Breaking changes:

• Commits with BREAKING CHANGE: in body or footer
• Commits with ! after type (e.g., feat!:, fix!:)
• Removed features or changed APIs

MINOR (0.x.0) - New features:

• Commits starting with feat:
• New plugins or commands
• New capabilities added

PATCH (0.0.x) - Bug fixes and small improvements:

• Commits starting with fix:
• Commits starting with refactor:, docs:, test:, chore:
• Performance improvements
• Documentation updates

Default: If no conventional commits, use PATCH.

Instructions

1. Analyze Changes

Get the current version and commits since last tag:

# Get latest tag (current version)
git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0"

# Get commits since last tag
git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --oneline

# Get detailed commit messages for analysis
git log $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --format="%h %s%n%b"

2. Determine Version Bump

Based on commits:

• Check for BREAKING CHANGE or ! → MAJOR
• Check for feat: → MINOR
• Otherwise → PATCH

Calculate new version:

# Example: current v1.2.3
# MAJOR: v2.0.0
# MINOR: v1.3.0
# PATCH: v1.2.4

3. Build Executables

Use the Makefile to build for all platforms:

make build-all

This builds:

• bin/day-night-cycle-darwin-amd64 (macOS Intel)
• bin/day-night-cycle-darwin-arm64 (macOS Apple Silicon)

4. Create Git Tag

git tag -a v1.3.0 -m "Release v1.3.0"
git push origin v1.3.0

5. Generate Release Notes

Write minimalist notes following this format:

[One sentence summary of the release]

## Changes

- [User-facing change 1]
- [User-facing change 2]
- [User-facing change 3]

## Fixes

- [Bug fix 1]
- [Bug fix 2]

Guidelines:

• Be concise: One line per change, no elaboration unless critical
• User perspective: What changed for users, not how it was implemented
• Skip noise: Don't mention refactoring, internal cleanup, or dependency updates unless they affect users
• Group logically: Features, fixes, breaking changes
• No emotion: Avoid "exciting", "amazing", "awesome" - just facts
• No redundancy: If the commit message is clear, use it directly

Examples of good vs bad notes:

✅ Good:

• Add support for Cursor IDE theme switching
• Fix launchd schedule generation for negative timezones
• Remove deprecated Name field from LocationConfig

❌ Bad:

• We're excited to announce amazing new Cursor IDE support! 🎉
• This release includes a critical bug fix that was causing issues
• Refactored internal plugin architecture for better maintainability

6. Create GitHub Release

CRITICAL: You MUST always write custom release notes. Never use auto-generated notes.

Write the release notes to a temporary file, then use the Makefile to create the release:

# Write notes to a file
cat > /tmp/release-notes.md << 'EOF'
[One sentence summary of the release]

## Changes

- [User-facing change 1]
- [User-facing change 2]

## Fixes

- [Bug fix 1]
EOF

# Create release with custom notes
make release RELEASE_NOTES=/tmp/release-notes.md

This will:

• Build all platform binaries with make build-all
• Upload binaries to GitHub
• Create release with your custom notes from the file
• Use the tag created earlier

IMPORTANT: Always provide the RELEASE_NOTES parameter. The Makefile has a fallback to auto-generated notes, but you must never use it. Claude-written release notes are required for all releases.

Checklist

Before completing the release:

• Analyzed all commits since last tag
• Determined correct semantic version bump
• Calculated new version number
• Built executables with make build-all
• Verified build artifacts exist in bin/
• Created git tag with new version
• Pushed tag to origin
• Generated minimalist release notes (REQUIRED)
• Wrote release notes to /tmp/release-notes.md (REQUIRED)
• Created GitHub release with make release RELEASE_NOTES=/tmp/release-notes.md (REQUIRED)
• Verified release appears on GitHub with binaries and custom release notes

Example Workflow

User: "Cut a new release"

Expected workflow:

1. Run git describe --tags --abbrev=0 to get current version (e.g., v1.2.0)
2. Run git log v1.2.0..HEAD --format="%h %s%n%b" to get commits
3. Analyze commits:
   • Found: feat: add Cursor IDE plugin
   • Found: fix: handle timezone edge case
   • Found: refactor: simplify main.go
4. Determine: MINOR bump (feat: found, no breaking changes)
5. Calculate: v1.2.0 → v1.3.0
6. Run make build-all to build binaries
7. Create tag: git tag -a v1.3.0 -m "Release v1.3.0"
8. Push tag: git push origin v1.3.0
9. Write release notes to file:

   cat > /tmp/release-notes.md << 'EOF'
   Add Cursor IDE support and fix timezone handling.
   
   ## Changes
   - Add support for Cursor IDE theme switching
   
   ## Fixes
   - Fix timezone handling for negative offsets
   EOF
   

10. Run make release RELEASE_NOTES=/tmp/release-notes.md to create GitHub release

Common Scenarios

First Release (No Tags)

If git describe --tags fails, this is the first release:

• Start with v0.1.0 or v1.0.0 depending on maturity
• Include all commits in release notes summary
• Focus on what the tool does, not individual commits

Patch Release (Only Fixes)

If only fix:, docs:, chore:, refactor: commits:

• Bump PATCH version
• Keep notes very brief
• Group related fixes

Major Release (Breaking Changes)

If BREAKING CHANGE: found:

• Bump MAJOR version
• Clearly list breaking changes first
• Explain migration path if needed

Notes

• CRITICAL: Always generate and use custom release notes - never rely on auto-generated notes
• Always write release notes to /tmp/release-notes.md before running make release
• Always pass RELEASE_NOTES=/tmp/release-notes.md to the make release command
• Always verify the Makefile is being used correctly
• The make release target requires GitHub CLI (gh)
• Never release from a dirty working tree (warn user if uncommitted changes)
• Minimize release note length while maintaining clarity
• When in doubt, bump PATCH (smallest change)
• Breaking changes require explicit documentation