My semantic release

My Semantic Release

Automate semantic versioning, changelog generation, and release workflows.

⚡ Quick Start

Quick version bump check:

# Analyze commits since last tag
git log v1.2.0..HEAD --format='%s' | grep -E '^feat:|^fix:'
git log v1.2.0..HEAD --format='%b' | grep 'BREAKING CHANGE'

# Decision:
# - BREAKING CHANGE present → MAJOR (1.2.0 → 2.0.0)
# - feat: present → MINOR (1.2.0 → 1.3.0)
# - fix: present → PATCH (1.2.0 → 1.2.1)

Quick release workflow:

1. Update CHANGELOG.md with new version section
2. Bump version in package.json / Cargo.toml / etc.
3. Commit: chore(release): X.Y.Z
4. Tag: git tag -a vX.Y.Z -m "Release vX.Y.Z"
5. Push: git push origin main && git push origin vX.Y.Z

Overview

This skill provides workflows for:

1. Semantic versioning — Determine version bumps from conventional commits
2. Changelog generation — Auto-generate CHANGELOG.md from commit history
3. Conventional commits — Format commits for release automation
4. Release workflow — Full release automation chain

Prerequisites

The project should follow Conventional Commits specification:

• feat: — New features (minor version bump)
• fix: — Bug fixes (patch version bump)
• BREAKING CHANGE: — Breaking changes (major version bump)
• docs:, style:, refactor:, test:, chore: — No version bump

Workflows

1. Generate Changelog

Trigger phrases: "generate changelog", "update CHANGELOG.md", "create changelog"

Steps:

1. Find last release tag/version
2. Collect commits since last release
3. Categorize by conventional commit type
4. Write/update CHANGELOG.md

Concrete commands:

# Find last tag
git describe --tags --abbrev=0

# Get commits since last tag
git log v1.2.0..HEAD --oneline --no-decorate

Changelog format:

## [Unreleased]

### Added
- New features...

### Fixed
- Bug fixes...

## [1.2.0] - 2026-04-16
...

2. Determine Version Bump

Trigger phrases: "what version bump", "should this be major/minor/patch", "semantic version"

Steps:

1. Analyze commits since last tag
2. Check for BREAKING CHANGE markers
3. Check for feat: commits
4. Check for fix: commits
5. Recommend version bump

Concrete analysis commands:

# Get all commits since last tag with bodies (to check for BREAKING CHANGE)
git log v1.2.0..HEAD --format='%s%n%b%n---' | grep -E '(BREAKING CHANGE:|^feat:|^fix:|^docs:|^style:|^refactor:)'

# Quick count by type
git log v1.2.0..HEAD --format='%s' | grep -c '^feat:'  # count features
git log v1.2.0..HEAD --format='%s' | grep -c '^fix:'   # count fixes
git log v1.2.0..HEAD --format='%b' | grep -c 'BREAKING CHANGE'  # count breaking

Decision rules:

• BREAKING CHANGE: in any commit → MAJOR (1.2.0 → 2.0.0)
• feat: present → MINOR (1.2.0 → 1.3.0) (if no breaking change)
• fix: present → PATCH (1.2.0 → 1.2.1) (if no feat/breaking)
• Only docs/style/refactor → No bump

3. Format Conventional Commit

Trigger phrases: "format this commit", "conventional commit for release", "write commit message for feat/fix"

Use this to write properly formatted commit messages that feed into release automation:

Type	Use when	Example
feat	Adding features	feat(auth): add JWT token support
fix	Fixing bugs	fix(api): handle null response
docs	Documentation only	docs(readme): update install steps
style	Formatting, no logic	style: run biome format
refactor	Code restructuring	refactor(db): extract connection pool
test	Adding tests	test(auth): add login flow tests
perf	Performance improvements	perf(db): optimize query
chore	Maintenance tasks	chore(deps): update dependencies

4. Full Release Workflow (Chained)

Trigger phrases: "create release", "release version", "bump version and release", "ship it"

This workflow chains all operations in sequence:

┌─────────────────────────────────────────────────────────────┐
│  STEP 0: PRE-RELEASE VERIFICATION (Critical!)                 │
│  └─> Run full check suite (biome, tests, typecheck)          │
│      └─> Fix any format/lint issues BEFORE tagging           │
├─────────────────────────────────────────────────────────────┤
│  STEP 1: Semantic Versioning                                  │
│  └─> Analyze commits since last tag                          │
│      └─> Detect major/minor/patch (or none)                  │
├─────────────────────────────────────────────────────────────┤
│  STEP 2: Changelog Generation                                 │
│  └─> Generate CHANGELOG.md with new version section            │
├─────────────────────────────────────────────────────────────┤
│  STEP 3: Version Bump                                         │
│  └─> Update package.json, Cargo.toml, etc.                 │
│      └─> Commit version bump                                 │
├─────────────────────────────────────────────────────────────┤
│  STEP 4: Release Commit & Tag                                 │
│  └─> Commit: "chore(release): X.Y.Z"                        │
│      └─> Tag: vX.Y.Z                                         │
└─────────────────────────────────────────────────────────────┘

⚠️ CRITICAL: Pre-Release Verification

ALWAYS run full checks before tagging. CI failures after tagging require force-pushing the tag:

# Step 0: Verify everything passes BEFORE tagging
just check  # or: npm run check, make check, etc.

# Common pre-release failures:
# 1. Biome format issues (package.json indentation, import sorting)
# 2. Test failures
# 3. TypeScript errors
# 4. Missing test coverage

Concrete execution (example: 1.2.0 → 1.3.0):

# STEP 1: Determine version (found feat: commits, no breaking changes)
# Decision: MINOR bump → 1.3.0

# STEP 2: Update CHANGELOG.md (prepend new section)
# Edit file manually or use automated tool

# STEP 3: Bump version in package.json
# Using jq:
cat package.json | jq '.version = "1.3.0"' > package.json.tmp && mv package.json.tmp package.json

# Or edit Cargo.toml manually:
# version = "1.3.0"

# STEP 4: Stage changes
git add -A

# STEP 5: Commit the release
git commit -m "chore(release): 1.3.0"

# STEP 6: Tag the release
git tag -a "v1.3.0" -m "Release v1.3.0"

# STEP 7: Push
git push origin main
git push origin v1.3.0

Integration with VCS

This skill assumes you have version control set up with git. The release workflow:

1. Reads commit history via git
2. Writes changelog, version bumps, commits, tags
3. Uses git for all VCS operations

Custom Release Tools

Some projects have custom release automation (e.g., just release, make release, npm run release) that handles tagging and pushing automatically. Check first before manually tagging.

Signs of custom release tools:

• justfile, Makefile, or package.json scripts with release target
• Workflow files that trigger on tags but also create tags themselves
• Documentation saying "run just release" instead of manual tagging

If custom tool exists:

1. Bump version in package.json (or relevant file)
2. Update CHANGELOG.md
3. Commit with chore(release): X.X.X message
4. Run the custom tool (e.g., just release) - it will tag and push for you

Do NOT manually run git tag if the tool does it automatically - this creates duplicate or mismatched tags.

Example: npm Project with just release

A typical npm project with just release which:

• Reads version from package.json
• Validates version matches conventional commits
• Creates and pushes the tag automatically
• Monitors GitHub Actions with auto-retry (up to 3 times)

Correct workflow:

# 1-3. Update files and commit
git add -A
git commit -m "chore(release): X.X.X"

# 4. Run the tool (handles everything including monitoring)
just release

Wrong workflow (creates tag at wrong commit):

git tag -a vX.X.X -m "Release vX.X.X"  # DON'T do this manually!
just release  # Tool also tries to create tag - conflict!

Advanced: Skip monitoring

RELEASE_NO_WATCH=1 just release  # Push tag but don't watch CI

Common CI Failures & Recovery

Failure: Biome Format Errors

Symptom: CI fails with "Formatter would have printed the following content"

Common causes:

• jq modified package.json with wrong indentation (2 spaces vs tabs)
• New test files have unsorted imports
• File saved without final newline

Fix:

# Local fix
just fix  # or: npx @biomejs/biome check --write .

# Commit the fix
git add -A
git commit -m "style: fix biome formatting"

# Move tag to fixed commit (if already pushed)
git tag -d vX.Y.X
git tag -a vX.Y.X -m "Release vX.Y.X" <new-commit-hash>
git push --force origin vX.Y.X

Failure: Test Failures

Symptom: CI fails during test phase

Fix:

# Run tests locally
just test

# Fix failures, commit, retag

Failure: TypeScript Errors

Symptom: npx tsc --noEmit fails

Fix:

# Check types locally
npx tsc --noEmit --skipLibCheck

# Fix errors, commit, retag

Example Release Session

Before: package.json has "version": "1.2.0", last tag is v1.2.0

# User: "ship it"

# 1. Determine version bump
$ git log v1.2.0..HEAD --format='%s' | grep -E '^feat:|^fix:'
feat: add user profiles
fix: handle auth edge case
→ Recommendation: MINOR bump (1.2.0 → 1.3.0)

# 2. Update CHANGELOG.md (prepend new section)
$ cat > /tmp/changelog_section.md << 'EOF'
## [1.3.0] - 2026-04-19

### Added
- User profiles feature

### Fixed
- Auth edge case handling
EOF
$ cat /tmp/changelog_section.md CHANGELOG.md > CHANGELOG.md.new
$ mv CHANGELOG.md.new CHANGELOG.md

# 3. Bump version in package.json
$ cat package.json | jq '.version = "1.3.0"' > package.json.tmp
$ mv package.json.tmp package.json

# 4. Stage changes
$ git add -A
$ git status --short  # shows modified: CHANGELOG.md, package.json

# 5. Commit the release
$ git commit -m "chore(release): 1.3.0"

# 6. Tag and push
$ git tag -a v1.3.0 -m "Release v1.3.0"
$ git push origin main && git push origin v1.3.0

# After: v1.3.0 tag exists, package.json shows 1.3.0, CHANGELOG.md updated

When NOT to Use This Skill

• Daily commit operations → Use git
• Checking what changed → Use git
• Push to GitHub → Use git
• Worktree management → Use git

Use this skill only when the conversation is about releases, versioning, or changelog.

Troubleshooting

Issue	Solution
CI fails with "Formatter would have printed..."	Run just fix or npx @biomejs/biome check --write . → commit → retag
Test failures in CI	Run just test locally → fix → commit → git tag -d vX.Y.Z && git tag -a vX.Y.Z
TypeScript errors (tsc --noEmit fails)	npx tsc --noEmit --skipLibCheck → fix → commit → retag
jq broke package.json indentation	Run biome fix: npx @biomejs/biome check --write package.json
Tag already pushed to wrong commit	git tag -d vX.Y.Z && git tag -a vX.Y.Z <new-hash> && git push --force origin vX.Y.Z
Custom release tool conflicts with manual tag	Read justfile first — never manually tag if tool handles it

Common Agent Mistakes

❌ Wrong: Bumping version manually with npm version or editing package.json by hand ✅ Right: Use conventional commits → let semantic-release calculate the bump automatically

❌ Wrong: Writing changelog entries by hand from memory ✅ Right: Generate from git log --format='%s' or use conventional-changelog tools

❌ Wrong: Releasing without running checks first ✅ Right: just check (or npm run check) → fix issues → then tag

❌ Wrong: Using feat: for internal refactoring ✅ Right: Use refactor: or chore: — feat: triggers a minor bump

❌ Wrong: Manually tagging when a custom release tool exists ✅ Right: Check justfile/package.json for release target first

Related Skills

• @skills/worktrunk — For release branch management via worktrees
• @skills/my-tech-stack — For tool recommendations (biome, just, mise, etc.)
• @skills/my-workflow — For commit discipline before cutting a release