create-release-workflow
/create-release-workflow
Use when creating a new release — drafting a changelog entry, creating git tags, publishing via GitHub Releases, or updating README install examples to pin to the latest tagged version.
- Author
- mhenke ↗
- Repository
- john-ousterhout-skills ↗
- Licence
- MIT
- Last repository change
- 13.06.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 13.06.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when creating a new release — drafting a changelog entry, creating git tags, publishing via GitHub Releases, or updating README install examples to pin to the latest tagged version.
Original author description
Use when creating a new release — drafting a changelog entry, creating git tags, publishing via GitHub Releases, or updating README install examples to pin to the latest tagged version.
How it works
- Overview
- Version Prompting
- Setup
- Process
- Troubleshooting
- Version Contract
- Related
SKILL.md preview
---
name: create-release-workflow
description: Use when creating a new release — drafting a changelog entry, creating git tags, publishing via GitHub Releases, or updating README install examples to pin to the latest tagged version.
license: MIT
metadata:
internal: true
---
# Release Workflow
## Overview
Standardized release process: draft CHANGELOG entry → git tag → GitHub release → update README → commit.
See [CHANGELOG.md](/CHANGELOG.md).
## Version Prompting
Before starting the process, determine the next version:
```bash
git describe --tags --abbrev=0
```
This prints the latest tag (e.g., `v0.1.0`). Decide the bump type:
- **Major** (1.0.0): Breaking behavioral rules, SKILL.md structure, or plugin compatibility
- **Minor** (0.2.0): New rules, commands, or ADRs
- **Patch** (0.1.1): Bug fixes, docs, non-breaking refactors
No prior tag? Start at `v0.1.0`.
## Setup
Before starting:
- `git status` — working tree must be clean
- `git log origin/main..HEAD` — no unpushed commits
- `git fetch` — remote accessible
## Process
### 1. Draft CHANGELOG Entry
Read `CHANGELOG.md` to find the current latest version. Read the git log since the last tag:
```bash
git log --oneline $(git describe --tags --abbrev=0)..HEAD
# If no prior tag:
git log --oneline --all
```
Categorize commits: **Added** (`feat:`), **Changed** (`refactor:`, `perf:`), **Fixed** (`fix:`), **Docs** (`docs:`). Update `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/) format.
### 2. Create Git Tag
```bash
git tag -a v{NEW_VERSION} -m "Release v{NEW_VERSION}"
git push origin v{NEW_VERSION}
```
### 3. Create GitHub Release
Extract the current version's entry from `CHANGELOG.md` and use it as the release body:
```bash
# Extract changelog section for this version
python3 << 'PYEOF' > /tmp/changelog-entry.md
import sys
with open('CHANGELOG.md') as f:
content = f.read()
version = 'v{NEW_VERSION}'
start = content.find(f'## [{version}]')
if start == -1:
print(f"Error: no CHANGELOG entry for {version}", file=sys.stderr)
sys.exit(1)
end = content.find('\n## [', start + 1)
if end == -1:
end = content.find('\n[Unreleased]:', start)
if end == -1:
end = len(content)
print(content[start:end].strip())
PYEOF
gh release create v{NEW_VERSION} \
--title "v{NEW_VERSION}" \
--notes-file /tmp/changelog-entry.md
```
### 4. Update README Install Examples
Search README.md for `raw.githubusercontent.com/mhenke/john-ousterhout-skills/` followed by a version reference. Replace with the new version tag. The `/plugin install` commands don't need URL changes.
### 5. Commit
```bash
git add CHANGELOG.md README.md
git commit -m "chore: release v{NEW_VERSION}"
git push origin main
```
## Troubleshooting
| Step | Failure | Fix |
|------|---------|-----|
| 2. Tag push | `git push origin v{NEW_VERSION}` fails (tag exists) | Tag may already exist remotely. Run `git tag -d v{NEW_VERSION}` locally, then re-push. Or bump to next patch version. |
| 3. Release creation | `gh release create` or changelog extraction fails | GitHub CLI not authenticated? Run `gh auth status`. Changelog extraction failed? Verify the version heading in CHANGELOG.md matches `v{NEW_VERSION}` exactly. Or create the release manually at the GitHub URL. |
| 4. README update | No `main` reference found in README | The install examples may already point to a tag. Update them to the new tag directly. |
| 5. Push rejected | Remote has new commits | `git pull --rebase origin main`, resolve conflicts, re-push. Re-do steps 1-4 if CHANGELOG or README conflicts. |
## Version Contract
- Tagged releases are stable snapshots with a documented CHANGELOG
- The `main` branch is the development edge — may contain unreleased changes
- Users pinning to a tag get stability; users on `main` get the latest
- No formal SemVer guarantee until v1.0.0 — 0.x range acknowledges rapid evolution
## Related
- [Keep a Changelog](https://keepachangelog.com/) — changelog format reference
- `references/version-examples.md` — version bump examples
Files in this package (2)
- SKILL.md 4 KB
- references/version-examples.md 1 KB
Versions
The database has no other skills named create-release-workflow.
Database snapshot: 13.11.2026 · package version f0af8f513170 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100create-release
Automate semantic version releases across project types by detecting version files, bumping versions, updating changelogs, creating git tags, and optionally publishing GitHub releases. Use when users ask to cut a release, bump the version, prepare a new version, tag a release,… - 100release-notes
Write release notes or a changelog entry from git history. Use when the user asks for release notes, a changelog, "what changed since the last release", or a summary of commits between two tags or branches. - 100changelog
Write release notes or a CHANGELOG.md entry from git history. Use when the user says "write the changelog", "release notes for v2.3", "what changed since the last release/tag", or is preparing a release or version bump. - 100release-it
release-it configuration, setup, troubleshooting, and plugin development. Triggers on .release-it.* config files, release-it CLI or programmatic usage, version bumping, changelog generation, npm publishing, GitHub/GitLab releases, git tagging, hooks lifecycle, pre-release… - 95release-manager
Create new AILANG releases with version bumps, changelog updates, git tags, and CI/CD verification. Use when user says "ready to release", "create release", mentions version numbers, or wants to publish a new version. - 100backfill-releases
Creates the missing git tags and GitHub releases for every version a beachball-published repository has already shipped, from its CHANGELOG.json files. Use when moving a repository onto GitHub releases, or when asked to backfill releases or tag old versions. Runs only when invoked by name.