Skip to content
Skills Library
Programming · Automation

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.

Licence
MIT
Last repository change
13.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 13.06.2026, without references to retired models or APIs.

Licence

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

  1. Overview
  2. Version Prompting
  3. Setup
  4. Process
  5. Troubleshooting
  6. Version Contract
  7. Related
Original SKILL.md headings · 114 lines, 543 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.