| name | release-manager |
| description | Release management: semantic versioning, changelog generation from conventional commits, release readiness checklists, hotfix procedures, rollback plans, and release branch strategy |
Release Manager Skill
When to activate
- Planning and coordinating a software release
- Generating a changelog from commit history
- Determining the correct semantic version bump for a release
- Running release readiness checks before deploying
- Managing a hotfix or emergency release process
- Setting up a release branch strategy (Git Flow, trunk-based, etc.)
When NOT to use
- CI/CD pipeline configuration — use the cicd skill
- Deployment infrastructure setup — use the docker or kubernetes skills
- Post-release incident management — use the incident-commander agent
- npm publish specifically — use the npm publish workflow
Instructions
Semantic versioning
Determine the version bump for [release].
Current version: [X.Y.Z]
Changes in this release: [describe or paste commit list]
Semantic versioning rules (semver.org):
MAJOR (X): breaking change — existing integrations will break
Examples: removed API endpoint, changed function signature, dropped Node version support
When: any commit with "BREAKING CHANGE:" in body, or "!" after type (feat!: ...)
MINOR (Y): new functionality, backwards-compatible
Examples: new API endpoint, new optional parameter, new feature behind a flag
When: commits with type "feat:"
PATCH (Z): backwards-compatible bug fix
Examples: fix a bug, update dependency (non-breaking), improve error message
When: commits with type "fix:", "perf:", "refactor:", "docs:" (without new features)
Conventional commit types:
- feat: → MINOR bump
- fix: → PATCH bump
- feat!: or BREAKING CHANGE: → MAJOR bump
- chore:, docs:, style:, test:, refactor: → PATCH (or no bump, your choice)
- perf: → PATCH bump
Given your changes: [input]
Recommended version: [X.Y.Z → A.B.C]
Reasoning: [which commits triggered which bump]
Changelog generation
Generate a changelog for [version release].
Version: [X.Y.Z]
Date: [YYYY-MM-DD]
Commits since last release: [paste git log --oneline output or describe changes]
Conventional commit format: type(scope): description
Example: feat(auth): add OAuth2 login support
Changelog format (Keep a Changelog standard):
## [X.Y.Z] — YYYY-MM-DD
### Breaking Changes
- [description of breaking change + migration path]
### Added
- [feat: commits → user-facing description]
- [feat(scope): commits grouped by area]
### Changed
- [changes to existing functionality]
### Fixed
- [fix: commits → what was broken and now works]
### Security
- [security-relevant changes — vulnerabilities patched, permissions tightened]
### Deprecated
- [features that will be removed in a future major version]
### Removed
- [removed features — breaking, goes in Breaking Changes if removal is the break]
Rules for good changelog entries:
- Write for users, not for developers
- "Add OAuth2 login" not "feat(auth): implement oauth2 handler"
- Include migration steps for breaking changes
- Group by impact, not by file or system
Generate the changelog for my release from the commits I provide.
Release readiness checklist
Run release readiness checks for [version].
Release type: [major / minor / patch / hotfix]
Target environment: [staging → prod / direct to prod / canary]
Deployment time: [scheduled / on-call standing by / business hours only]
Pre-release checklist:
CODE QUALITY:
□ All CI checks passing (tests, lint, type check, security scan)
□ Code review completed for all changes in this release
□ No open P1/P2 bugs targeting this release that aren't fixed
□ No unresolved merge conflicts
TESTING:
□ Unit tests passing (coverage ≥ threshold)
□ Integration tests passing
□ E2E tests passing on staging environment
□ Manual smoke test of critical user journeys on staging
□ Performance: no regression vs. baseline (check p99 latency)
□ Database migrations tested on a staging DB of prod-like size
COMMUNICATIONS:
□ Release notes drafted and approved
□ Customer-facing changelog ready (if changes affect users)
□ Support team briefed on what's changing
□ Sales/CS briefed if release includes new features they need to demo
□ Status page: any planned maintenance window posted
DEPLOYMENT:
□ Deployment runbook reviewed and up to date
□ Rollback plan defined and tested
□ Database migration rollback confirmed (or migration is forward-only with documented reason)
□ Feature flags configured for gradual rollout (if applicable)
□ On-call engineer aware of deployment timing
□ Monitoring dashboards open: error rate, p99 latency, key business metrics
POST-DEPLOY VALIDATION (first 30 min):
□ Health endpoint returning 200
□ Error rate within normal range
□ Key user flows working (smoke test)
□ Database migration completed cleanly
□ No unusual alerts firing
SIGN-OFF:
□ Engineering lead sign-off
□ Product owner sign-off (for minor/major releases)
□ [Optional] Security review for security-sensitive changes
Generate the checklist for my release type and deployment model.
Hotfix procedure
Execute a hotfix for [incident/bug].
Issue severity: [P1 — production down / P2 — major degradation]
Issue: [describe the bug and its impact]
Current production version: [X.Y.Z]
Hotfix branch from: [main / release/X.Y.Z]
Hotfix procedure:
STEP 1 — Create hotfix branch:
git checkout -b hotfix/X.Y.Z+1 main # Branch from main (or the current prod tag)
# If using Git Flow: git flow hotfix start X.Y.Z+1
STEP 2 — Apply the fix:
[Make the minimal change to fix the issue — no opportunistic cleanup]
[Write a test that reproduces the bug, then verify the fix passes it]
STEP 3 — Version bump:
Bump version to X.Y.Z+1 (PATCH)
Update CHANGELOG.md with the fix
STEP 4 — PR and review:
PR from hotfix/X.Y.Z+1 → main
Expedited review: minimum 1 senior reviewer
CI must pass: no exceptions for P1 hotfixes — if CI is broken, fix CI first
STEP 5 — Merge and tag:
git tag -a vX.Y.Z+1 -m "Hotfix: [description]"
git push origin vX.Y.Z+1
STEP 6 — Deploy:
Follow deployment runbook with expedited timeline
Keep monitoring dashboards open for 30 minutes post-deploy
Confirm the fix resolves the incident before declaring resolved
STEP 7 — Backport to develop:
git checkout develop
git cherry-pick [hotfix commit SHA]
# Ensures the fix is in the next regular release
STEP 8 — Post-incident:
Update CHANGELOG.md on main and develop
Schedule PIR for P1 hotfixes (within 48 hours)
Hotfix rules:
- Fix ONLY the reported bug — no other changes in the hotfix branch
- Hotfix bypasses normal release process but NOT code review
- Hotfix automatically increments PATCH version
Write the hotfix plan for my specific bug.
Release strategy
Design a release branching strategy for [team].
Team size: [X engineers]
Release frequency: [daily / weekly / monthly]
Deployment model: [continuous / gated releases / scheduled windows]
Current problem: [too slow / too risky / no process / merge conflicts]
Strategy comparison:
TRUNK-BASED DEVELOPMENT (recommended for most teams):
- Everyone commits to main daily
- Releases tagged from main at any time
- Feature flags hide incomplete features
- Best for: CI/CD, small teams, frequent releases
- Pros: simple, fast, no long-lived branches
- Cons: requires discipline + feature flags infrastructure
GIT FLOW (for scheduled releases):
- main: production
- develop: integration branch
- feature/X: individual features → merge to develop
- release/X.Y: release preparation → merge to main + develop
- hotfix/X: emergency fixes → merge to main + develop
- Best for: mobile apps, on-prem software with release cycles
- Cons: complex, merge conflicts, slow
GITHUB FLOW (lightweight):
- main: always deployable
- feature/X: any work → PR → merge to main → deploy
- Best for: web services deploying continuously
- Pros: simple, fast, no release branches
For your team profile:
[Recommend one strategy with rationale and setup instructions]
Set up the recommended strategy for my team with git commands and CI/CD integration points.
Example
User: We're about to release v2.0.0 of our SaaS API. It has breaking changes (removed 3 deprecated endpoints). How do I communicate this and execute the release?
Claude's release plan:
Version: 2.0.0 (MAJOR bump — breaking change = removed endpoints)
Changelog entry:
## [2.0.0] — 2026-05-20
### Breaking Changes
- Removed deprecated endpoints: `GET /api/v1/users/legacy`, `POST /api/v1/auth/old`, `DELETE /api/v1/items/purge`
→ **Migration:** Use `GET /api/v2/users`, `POST /api/v2/auth/login`, `DELETE /api/v2/items` respectively.
→ Full migration guide: docs.yourapi.com/migration/v1-to-v2
### Added
- [other additions]
### Fixed
- [bug fixes]
Communication sequence:
- 4 weeks before: Email to all API key holders — "Breaking changes coming in v2.0.0 on [date]. Action required."
- 2 weeks before: Second reminder + migration guide link
- 1 week before: Final warning + offer of 2-week extension for customers who request it
- Release day: Release notes posted, status page note, support team briefed
- Post-release: Monitor for 400 errors on the removed endpoints — expect spike from slow migrators
Release readiness gates for a breaking major:
