Release Orchestrator Skill Skill

Release Orchestrator Skill

Purpose

Automate the entire release process from version calculation to deployment, ensuring consistent and reliable releases across environments.

When to Use

Creating new releases
Generating changelogs
Deploying to staging/production
Tagging releases in git
Publishing packages to registries
Creating GitHub/GitLab releases

Supported Workflows

Semantic Versioning

MAJOR: Breaking changes (v1.0.0 → v2.0.0)
MINOR: New features (v1.0.0 → v1.1.0)
PATCH: Bug fixes (v1.0.0 → v1.0.1)
Pre-release: Alpha, beta, rc (v1.0.0-alpha.1)

Commit Conventions

Conventional Commits: feat:, fix:, chore:, docs:, etc.
Breaking Changes: BREAKING CHANGE in commit body
Scope: feat(api): add authentication

Package Types

npm/yarn: JavaScript/TypeScript packages
PyPI: Python packages
RubyGems: Ruby packages
Cargo: Rust crates
Go Modules: Go packages
Docker: Container images
GitHub Releases: Binary assets

Operations

1. Calculate Version

Analyze git history since last tag
Detect breaking changes, features, fixes
Apply semantic versioning rules
Handle pre-release versions

2. Generate Changelog

Parse conventional commits
Group by type (Features, Bug Fixes, Breaking Changes)
Include commit authors
Link to issues/PRs
Generate markdown format

3. Build Release Assets

Compile binaries (platform-specific)
Bundle JavaScript/TypeScript
Package Python wheels
Create Docker images
Generate checksums

4. Create Git Release

Create and push git tag
Update version in package files
Commit version bump
Create GitHub/GitLab release

5. Deploy to Environments

Staging deployment (automatic)
Production deployment (with approval)
Rollback capability
Health checks

Scripts

main.py

# Calculate next version
python scripts/main.py version --calculate

# Generate changelog
python scripts/main.py changelog --from=v1.0.0 --to=HEAD

# Create full release
python scripts/main.py release --type=minor

# Deploy to environment
python scripts/main.py deploy --environment=staging

# Rollback release
python scripts/main.py rollback --version=v1.2.3

Subcommands

version: Calculate semantic version

python scripts/main.py version --calculate
# Output: v1.3.0 (current: v1.2.5)

changelog: Generate changelog

python scripts/main.py changelog --from=v1.2.0 --to=HEAD
# Output: CHANGELOG.md with grouped commits

release: Create complete release

python scripts/main.py release --type=minor --dry-run
# Output: Preview of release (no changes)

deploy: Deploy to environment

python scripts/main.py deploy --environment=production --confirm
# Output: Deployment status and health checks

Configuration

Project Configuration

Create .release.json in project root:

{
  "versionFiles": [
    "package.json",
    "pyproject.toml",
    "Cargo.toml"
  ],
  "changelogFile": "CHANGELOG.md",
  "commitTypes": {
    "feat": "Features",
    "fix": "Bug Fixes",
    "docs": "Documentation",
    "perf": "Performance",
    "refactor": "Refactoring"
  },
  "deployments": {
    "staging": {
      "type": "kubernetes",
      "namespace": "staging",
      "autoPromote": false
    },
    "production": {
      "type": "kubernetes",
      "namespace": "production",
      "requiresApproval": true
    }
  }
}

Memory Integration

Stores release history:

{
  "topic": "release-history",
  "scope": "repository",
  "value": {
    "last_release": "v1.2.5",
    "release_date": "2025-10-15T10:00:00Z",
    "releases": [
      {
        "version": "v1.2.5",
        "date": "2025-10-15",
        "commits": 23,
        "type": "minor"
      }
    ],
    "deploy_preferences": {
      "auto_staging": true,
      "production_approval": true,
      "rollback_window": "24h"
    }
  }
}

Integration Points

With Test-First Change Skill

Run test suite before release
Block release if tests fail
Include test coverage in changelog

With PR Author/Reviewer Skill

Generate release PR
Include changelog in PR description
Require approvals for production

With Memory Hygiene Skill

Track release frequency
Monitor success rates
Record deployment patterns

With Dependency Guardian Skill

Check for vulnerable dependencies
Block release if critical CVEs found
Include dependency updates in changelog

Examples

Example 1: Calculate Next Version

Current version: v1.2.5

Recent commits:

feat(api): add user authentication
fix(ui): button alignment issue
chore: update dependencies

Command:

python scripts/main.py version --calculate

Output:

{
  "current": "1.2.5",
  "next": "1.3.0",
  "bump": "minor",
  "reason": "New features detected",
  "commits": {
    "features": 1,
    "fixes": 1,
    "chores": 1
  }
}

Example 2: Generate Changelog

Command:

python scripts/main.py changelog --from=v1.2.0 --to=HEAD --output=CHANGELOG.md

Output (CHANGELOG.md):

# Changelog

## [1.3.0] - 2025-10-20

### Features
- **api**: add user authentication (#123) @johndoe
- **ui**: implement dark mode toggle (#124) @janedoe

### Bug Fixes
- **ui**: button alignment issue (#125) @johndoe
- **api**: fix rate limiting bug (#126) @janedoe

### Chores
- update dependencies (#127) @johndoe

Example 3: Create Release

Command:

python scripts/main.py release --type=minor --dry-run=false

Steps executed:

✅ Calculate version: v1.2.5 → v1.3.0
✅ Generate changelog
✅ Update version in package.json
✅ Commit changes: "chore: release v1.3.0"
✅ Create git tag: v1.3.0
✅ Push to origin
✅ Create GitHub release
✅ Upload assets (if configured)

Output:

{
  "success": true,
  "version": "1.3.0",
  "tag": "v1.3.0",
  "release_url": "https://github.com/user/repo/releases/tag/v1.3.0",
  "assets": []
}

Example 4: Deploy to Staging

Command:

python scripts/main.py deploy --environment=staging --version=v1.3.0

Output:

{
  "success": true,
  "environment": "staging",
  "version": "v1.3.0",
  "deployment_id": "deploy-xyz123",
  "status": "healthy",
  "url": "https://staging.example.com",
  "health_checks": {
    "http": "passed",
    "database": "passed",
    "redis": "passed"
  }
}

Token Economics

Without Skill (Agent-driven release):

Analyze commits: 3,000 tokens
Calculate version: 2,000 tokens
Generate changelog: 4,000 tokens
Create release steps: 3,000 tokens
Explain process: 2,000 tokens
Total: 14,000 tokens

With Skill (Code execution):

Metadata: 50 tokens
SKILL.md: 350 tokens
Script execution: 0 tokens (returns result)
Result parsing: 150 tokens
Total: 550 tokens

Savings: 96.1% (13,450 tokens saved per release)

Success Metrics

Performance

Version calculation: <1 second
Changelog generation: <5 seconds
Full release process: <2 minutes
Deployment time: <5 minutes

Quality

Release automation rate: >95%
Failed releases: <5%
Rollback success: 100%
Changelog accuracy: 100%

Adoption

Projects using Skill: >80%
Manual releases: <10%
Developer satisfaction: >4.5/5

Safety Checks

Pre-Release

✅ All tests pass
✅ No uncommitted changes
✅ On default branch (main/master)
✅ No vulnerable dependencies (critical/high)
✅ Previous release successful

Post-Release

✅ Tag created successfully
✅ Version files updated
✅ Changelog generated
✅ Release notes published
✅ Deployment health checks pass

Rollback Conditions

Health checks fail
Error rate exceeds threshold
Manual rollback request
Deployment timeout

Error Handling

Git Errors

❌ No commits since last release (v1.2.5)
Recommendation: Make changes before creating release

Version Conflicts

❌ Version v1.3.0 already exists
Recommendation: Delete tag or increment version

Deployment Failures

❌ Deployment to staging failed: Connection timeout
Health checks: http=failed, database=passed
Recommendation: Check staging environment connectivity
Rollback: python scripts/main.py rollback --environment=staging

Advanced Features

Pre-release Versions

# Create alpha release
python scripts/main.py release --type=minor --prerelease=alpha
# Output: v1.3.0-alpha.1

# Create beta release
python scripts/main.py release --type=minor --prerelease=beta
# Output: v1.3.0-beta.1

# Promote to stable
python scripts/main.py release --type=minor
# Output: v1.3.0

Multi-Platform Builds

{
  "builds": [
    {"platform": "linux-x64", "output": "bin/app-linux"},
    {"platform": "darwin-x64", "output": "bin/app-macos"},
    {"platform": "windows-x64", "output": "bin/app-windows.exe"}
  ]
}

Deployment Strategies

Blue-Green: Zero downtime deployments
Canary: Gradual rollout (10% → 50% → 100%)
Rolling: Update instances incrementally

Limitations

Requires conventional commit format for best results
Cannot automatically resolve merge conflicts
Manual approval needed for production deployments
Rollback may require manual intervention for database migrations

References

See references/ for:

conventional-commits.md - Commit format specification
versioning-guide.md - Semantic versioning rules
deployment-strategies.md - Deployment patterns
troubleshooting.md - Common issues and solutions

Release Orchestrator Skill v1.0.0 - Ship with confidence

Agent Skills: Release Orchestrator Skill

Skill Files