Agent-Skills.md

Agent Skills: Release Skill

|

UncategorizedID: blueman82/conductor/release

Repository

blueman82/conductor
blueman82License: MIT
292

Skill Files

Browse the full folder contents for release.

Download Skill

Loading file tree…

skills/release/SKILL.md

Skill Metadata

Name
release
Description
|

Release Skill

Create consistent, safe software releases across any project type.

Invocation

/release                     # Interactive - detect and prompt
/release patch               # Bump patch version (0.0.X)
/release minor               # Bump minor version (0.X.0)
/release major               # Major version bump (X.0.0)
/release v2.5.0              # Set explicit version
/release --dry-run           # Preview without executing

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│                     RELEASE WORKFLOW                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Phase 1: Pre-flight Checks                                     │
│    ├─ Clean working tree?                                       │
│    ├─ On releasable branch? (main/master/release/*)             │
│    ├─ Tests passing?                                            │
│    └─ Detect project type & current version                     │
│                                                                 │
│  Phase 2: Version Bump                                          │
│    ├─ Calculate new version                                     │
│    ├─ Update version file(s)                                    │
│    └─ Update version references in docs                         │
│                                                                 │
│  Phase 3: Changelog & Docs                                      │
│    ├─ Generate changelog entry (if CHANGELOG.md exists)         │
│    ├─ Update README.md badges/versions (if applicable)          │
│    └─ Update CLAUDE.md version (if applicable)                  │
│                                                                 │
│  Phase 4: Build & Verify                                        │
│    ├─ Run build command (make build, npm build, etc.)           │
│    ├─ Run linters/formatters (gofmt, eslint, etc.)              │
│    └─ Verify build succeeded                                    │
│                                                                 │
│  Phase 5: Git Operations                                        │
│    ├─ Stage all changes                                         │
│    ├─ Commit: "chore(release): vX.Y.Z"                          │
│    ├─ Create annotated tag: vX.Y.Z                              │
│    └─ Push commits and tags                                     │
│                                                                 │
│  Phase 6: GitHub Release (optional)                             │
│    ├─ Generate release notes from commits                       │
│    └─ Create GitHub release via gh CLI                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Phase 1: Pre-flight Checks

1.1 Working Tree Status

git status --porcelain

STOP if uncommitted changes exist. Ask user to commit or stash first.

Exception: If --dry-run flag, continue but warn.

1.2 Branch Check

git branch --show-current

Allowed branches:

  • main, master - production releases
  • release/* - release branches
  • develop - pre-releases only (append -beta.N or -rc.N)

If on feature branch:

  1. Ask user: "Merge to main first?"
  2. If yes: git checkout main && git merge <feature-branch> --ff-only
  3. Continue release from main

1.3 Test Suite

Run tests if test command is detectable:

| Project Type | Test Command | |--------------|--------------| | Go | go test ./... | | Node.js | npm test or yarn test | | Rust | cargo test | | Python | pytest or python -m pytest | | Make-based | make test (if target exists) |

STOP if tests fail. Do not proceed with broken tests.

1.4 Project Detection

Detect project type by scanning for these files (in order):

| File | Type | Version Location | Build Command | |------|------|------------------|---------------| | VERSION | Generic | File contents | make build (if Makefile) | | package.json | Node.js | .version field | npm run build | | Cargo.toml | Rust | version = "X.Y.Z" | cargo build --release | | pyproject.toml | Python | version = "X.Y.Z" | python -m build | | go.mod | Go | Git tags only | go build ./cmd/... | | build.gradle | Java/Gradle | version 'X.Y.Z' | ./gradlew build | | pom.xml | Java/Maven | <version> tag | mvn package |

Extract current version from the detected source.

If no version file found, check latest git tag:

git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0"

Phase 2: Version Bump

2.1 Parse Current Version

Extract semantic version components: MAJOR.MINOR.PATCH[-PRERELEASE]

Examples:

  • 2.31.0 → major=2, minor=31, patch=0
  • 1.0.0-beta.1 → major=1, minor=0, patch=0, pre=beta.1

2.2 Calculate New Version

| Bump Type | Current | New | |-----------|---------|-----| | patch | 2.31.0 | 2.31.1 | | minor | 2.31.0 | 2.32.0 | | major | 2.31.0 | 3.0.0 | | explicit v2.35.0 | 2.31.0 | 2.35.0 |

Pre-release handling:

  • If current is 2.0.0-beta.1 and bump is patch → 2.0.0-beta.2
  • To exit pre-release: use explicit version or --graduate

2.3 Update Version Files

Update ALL version locations found:

VERSION file:

echo "X.Y.Z" > VERSION

package.json:

npm version X.Y.Z --no-git-tag-version
# Or edit directly with jq/sed

Cargo.toml:

version = "X.Y.Z"

pyproject.toml:

version = "X.Y.Z"

Go projects: Version comes from git tag, no file update needed.

Phase 3: Changelog & Documentation

3.1 CHANGELOG.md (if exists)

Generate changelog entry from commits since last tag:

git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

Format (Keep a Changelog style):

## [X.Y.Z] - YYYY-MM-DD

### Added
- New feature descriptions (from feat: commits)

### Changed
- Change descriptions (from refactor:, chore: commits)

### Fixed
- Bug fix descriptions (from fix: commits)

Categorize by conventional commit prefix:

  • feat: → Added
  • fix: → Fixed
  • refactor:, perf: → Changed
  • docs: → Documentation
  • chore:, build:, ci: → Maintenance (optional section)

Insert new section after # Changelog header, before previous releases.

3.2 README.md Updates

Search for version badges or references:

![Version](https://img.shields.io/badge/version-2.31.0-blue)

Update to new version if found.

3.3 CLAUDE.md Updates

If CLAUDE.md exists and contains version reference, update it:

**Current**: v2.31.0 - Description here

Update to:

**Current**: vX.Y.Z - Description here

Phase 4: Build & Verify

4.1 Detect Build Command

| Condition | Command | |-----------|---------| | Makefile with build target | make build | | Makefile with build-patch/minor/major | Use appropriate target | | package.json with build script | npm run build | | Cargo.toml | cargo build --release | | go.mod | go build ./... | | pyproject.toml | python -m build |

4.2 Execute Build

Run the detected build command. STOP if build fails.

# Example for Make-based projects
make build

4.3 Verify Artifacts

Check that expected artifacts exist:

  • Binary in expected location
  • No error output
  • Exit code 0

4.4 Run Linters/Formatters (CI Parity)

Run the same checks CI will run to avoid post-push failures:

| Language | Commands | |----------|----------| | Go | gofmt -l . && go vet ./... | | Node.js | npm run lint (if exists) | | Rust | cargo fmt --check && cargo clippy | | Python | ruff check . && black --check . |

STOP if linting fails. Fix before proceeding.

# Example for Go projects
gofmt -w .  # Auto-fix formatting
go vet ./...

Phase 5: Git Operations

5.1 Stage Changes

git add -A

5.2 Create Release Commit

git commit -m "chore(release): v${VERSION}

Release version ${VERSION}

Changes in this release:
$(git log $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD~1 --oneline --no-merges | head -20)
"

5.3 Create Annotated Tag

git tag -a "v${VERSION}" -m "Release v${VERSION}"

Tag format: Always prefix with v (e.g., v2.32.0)

5.4 Push to Remote

git push origin $(git branch --show-current)
git push origin "v${VERSION}"

Ask for confirmation before push unless --yes flag provided.

Phase 6: GitHub Release (Optional)

6.1 Check for gh CLI

gh --version

Skip this phase if gh not installed or not authenticated.

6.2 Generate Release Notes

gh api repos/{owner}/{repo}/releases/generate-notes \
  -f tag_name="v${VERSION}" \
  -f target_commitish="$(git branch --show-current)" \
  --jq '.body'

Or generate from commit log if API unavailable.

6.3 Create Release

gh release create "v${VERSION}" \
  --title "v${VERSION}" \
  --notes "${RELEASE_NOTES}" \
  --latest

For pre-releases:

gh release create "v${VERSION}" --prerelease

Flags Reference

| Flag | Effect | |------|--------| | --dry-run | Show what would happen, don't execute | | --skip-tests | Skip test suite execution | | --skip-build | Skip build step | | --skip-changelog | Don't update CHANGELOG.md | | --skip-push | Create commit/tag locally, don't push | | --skip-gh | Skip GitHub release creation | | --yes, -y | Skip all confirmations | | --prerelease | Mark as pre-release (beta/rc) |

Safety Mechanisms

  1. Dirty tree protection - Won't release with uncommitted changes
  2. Branch protection - Warns on non-release branches
  3. Test gate - Fails if tests don't pass
  4. Build verification - Fails if build breaks
  5. Confirmation prompts - Asks before destructive operations
  6. Dry-run mode - Preview entire workflow safely

Examples

Basic Patch Release

User: /release patch
Claude:
1. Detected Go project with VERSION file (current: 2.31.0)
2. New version: 2.31.1
3. Running tests... ✓
4. Updating VERSION file... ✓
5. Building... ✓
6. Creating commit and tag... ✓
7. Push to origin? [Y/n]

Minor Release with Changelog

User: /release minor
Claude:
1. Current version: 1.5.2 → New: 1.6.0
2. Found 12 commits since v1.5.2
3. Generated CHANGELOG.md entry with 3 features, 2 fixes
4. [Shows preview]
5. Proceed? [Y/n]

Dry Run

User: /release major --dry-run
Claude:
[DRY RUN] Would perform:
- Bump version: 2.31.0 → 3.0.0
- Update: VERSION, CLAUDE.md
- Run: make build
- Commit: "chore(release): v3.0.0"
- Tag: v3.0.0
- Push to origin/main
- Create GitHub release
No changes made.

Error Recovery

| Error | Recovery | |-------|----------| | Tests failed | Fix tests, re-run /release | | Build failed | Fix build, re-run /release | | Push rejected | git pull --rebase, then git push | | Tag exists | Delete with git tag -d vX.Y.Z, re-run | | GH release failed | Run gh release create manually |

If release partially completed:

# Undo commit (if not pushed)
git reset --soft HEAD~1

# Delete tag (if created)
git tag -d vX.Y.Z

# Start fresh
/release

Project-Specific Notes

Go Projects

  • Version lives in git tags, not files
  • If VERSION file exists, update it too
  • Build: go build ./cmd/... or make build

Node.js Projects

  • Use npm version for atomic version + tag
  • Or update package.json + package-lock.json manually
  • Build: npm run build if script exists

Rust Projects

  • Update Cargo.toml version field
  • Also update Cargo.lock: cargo update
  • Build: cargo build --release

Python Projects

  • Update pyproject.toml or setup.py
  • Build: python -m build
  • Consider PyPI publish: twine upload

Monorepos

  • May need to update multiple package.json/Cargo.toml
  • Consider workspace version commands
  • Tag format: package-name@X.Y.Z or vX.Y.Z