release-changelog
Standardized release workflow — version bump, Keep a Changelog formatting, and CI/CD pipeline integration with auto-tagging and release automation. Works for any language (Python, Rust, Node, Go, etc.
SKILL.mdskills/release-changelog/SKILL.md
GitHubRelease & Changelog Skill
Pattern
A release workflow where:
- Version is single-sourced in the project's canonical config file (e.g.
Cargo.toml,package.json,pyproject.toml,versionfile) - Changelog follows Keep a Changelog + SemVer format
- CI/CD auto-creates tags and releases on push to main/default branch
Detection triggers
Activate when the user says:
- "cut a release"
- "bump the version"
- "update the changelog"
- "create release notes"
- "prepare a release"
- "release version X.Y.Z"
Protocol
Step 1: Find the version source
Identify where the canonical version lives. Common locations by language:
| Language | File | Field |
|---|---|---|
| Rust | Cargo.toml |
version = "X.Y.Z" |
| JavaScript/Node | package.json |
"version": "X.Y.Z" |
| Python | pyproject.toml |
version = "X.Y.Z" |
| Go | version.go or internal/version/version.go |
Varies |
| Generic | VERSION file, gradle.properties, pom.xml |
Varies |
Bump the version to the target.
Step 2: Write the changelog entry
Add a section at the top of CHANGELOG.md:
## [X.Y.Z] - YYYY-MM-DD
Use these categories as needed:
### Added— new features### Changed— changes in existing functionality### Removed— removed features### Fixed— bug fixes### Security— security fixes### Performance Improvements— perf changes
Each bullet uses present tense, imperative mood. If a commit trace tool exists, include:
### Commit Trace
- Since `prev_version`: `sha1`, `sha2`, ...
Step 3: Verify pre-release gates
Run the project's own quality checks — do not assume specific tools:
- Lint: run project's linter (ruff, clippy, eslint, golangci-lint, etc.)
- Format: run project's formatter check (black, rustfmt, prettier, gofmt, etc.)
- Type check: if applicable (mypy, tsc, etc.)
- Tests: run project's test suite (pytest, cargo test, npm test, go test, etc.)
- Build: ensure the project builds/compiles cleanly
- Security: if applicable, run project's security scanner
Check what commands the project uses (look at scripts/, Makefile, package.json scripts, Justfile, Taskfile.yml, or CI workflow files).
Step 4: Commit and push
Commit the version bump and changelog changes. Push to the default branch.
Step 5: Verify pipeline automation
After push, confirm these automated workflows fire:
- Auto-tag workflow creates
vX.Y.Ztag from the version file change - Release workflow creates a GitHub/GitLab Release, runs tests, builds artifacts
- Versioned-doc sync workflow updates version references across files
If any workflow fails, fix and re-push.
When NOT to use
- The project doesn't use SemVer or Keep a Changelog
- The project has its own established release process (always defer to existing patterns)
- The user explicitly asks not to touch versioning or changelog
- You're just fixing a typo in the changelog — use direct edit, not the full protocol
Cross-references
- follow-existing-patterns — Always defer to the project's existing release conventions before applying this skill. Read 2-3 prior changelog entries and the version file first to match style.
- self-validate — Run validation after the release batch (version bump + changelog + push) to confirm everything took effect.
- verify-and-cite — Verify version numbers match between the version file, changelog, and CI configs before declaring done.
- universal-format-lint — Format the changelog after writing to match project's Markdown conventions.
- project-backup-status — Backup before starting the release process to guard against destructive mistakes.
- anti-premature-termination — Do not declare "release complete" until tags, CI, and docs sync have all been verified.
- todo-bootstrap — If the release involves many steps (multi-repo, multiple changelogs, coordinated tags), use a checklist.
- project-scripts — Discover build, test, and deploy scripts before cutting a release to ensure all release automation steps are accounted for.
- audit-project — Verify dependency health and build integrity before cutting a release.
- skill-loader — Apply the expanded release-task cap when deciding which release and validation skills should also be active.
- security-best-practices — Check for security advisories before releasing if the project has security-sensitive changes.
- git-workflow-conventional-commits — Conventional commit types determine changelog sections (feat→Added, fix→Fixed, etc.). Ensure commits follow conventions for automatic changelog generation.
- ci-cd-automation — CI/CD pipelines should trigger release workflows. release-changelog defines the release process; CI/CD automates it.
- shipping-and-launch — Run release-changelog first (version bump, changelog, tag), then shipping-and-launch (deploy, rollout, monitor).
CI/CD Workflow Reference (typical)
| Workflow | Trigger | Action |
|---|---|---|
| auto-tag | push to default branch changing version file | Creates git tag vX.Y.Z |
| release | tag push v*.*.* |
Release, tests, build artifacts |
| versioned-doc sync | tag push or version file change | Syncs version badges/docs |