Release

Release

Overview

Guides a professional release process: determines the version bump, writes structured release notes, updates the changelog, commits, tags, and pushes. Ensures consistency and quality across releases.

Announce at start: "I'm using the release skill to cut a new version."

When to Use

• Shipping a new version of a project
• User says "release", "cut a release", "ship it", "bump version"
• After implementation is complete and all tests pass

When NOT to use:

• Work-in-progress commits (just commit normally)
• Hotfixes that don't warrant a release (though they often do)

Authorship Rule

All commits and tags are authored by the user, not by Claude.

• Do NOT add Co-Authored-By: Claude or any AI attribution to commits
• Do NOT add Co-Authored-By trailers of any kind
• The commit author is whoever is configured in git config user.name and git config user.email
• This applies to the release commit, the tag, and any preparatory commits

Release Flow

Step 1: Pre-Flight Check

Before anything else:

1. Run tests. If they fail, stop. Do not release broken code.
2. Check git status. All changes should be staged or committed. Warn if there are uncommitted changes unrelated to the release.
3. Check current branch. Releases should typically come from main or a release branch. If on a feature branch, confirm with the user.
4. Read the current version. Check package.json, Cargo.toml, pyproject.toml, RELEASE-NOTES.md, git tags, or wherever the project tracks its version.

Step 2: Determine Version Bump

Read the commit history since the last release tag to understand what changed:

git log <last-tag>..HEAD --oneline

Apply Semantic Versioning:

Present the recommendation to the user:

Based on the changes since vX.Y.Z, I recommend a minor bump to vX.Y+1.0:

• [list key changes]

Does this look right, or would you prefer a different version?

Wait for confirmation before proceeding.

Step 3: Write Release Notes

Read the existing RELEASE-NOTES.md to match the project's established style and structure. The new entry must be consistent with previous entries in tone, heading levels, and formatting.

Release notes structure:

## vX.Y.Z (YYYY-MM-DD)

### [Section Header — describes the theme]

[Narrative paragraph explaining the headline change. What it is, why it matters, how it works at a high level.]

### [Additional sections as needed]

[Group related changes under descriptive headers. Not every change needs its own section — group small changes together.]

### Full Changelog

- type: description of change
- type: description of change

Rules:

• Lead with the most important change, not a chronological dump
• Use narrative paragraphs for significant features, not just bullet points
• Group related changes under meaningful section headers
• The Full Changelog at the bottom is a concise, complete list using conventional commit prefixes (feat:, fix:, refactor:, docs:, chore:)
• Update counts, tables, or summary stats if the project tracks them (e.g., skill count, phase count)
• Do NOT mention Claude, AI, or automation in the release notes

Step 4: Update Version References

Update the version string in every manifest file that exists:

Also check for README badges or version references.

Step 5: Commit

Stage all release-related changes and create a single release commit:

git add -A
git commit -m "release: vX.Y.Z — [one-line summary of headline change]"

No Co-Authored-By trailer. No AI attribution.

Step 6: Tag

Create an annotated tag:

git tag -a vX.Y.Z -m "vX.Y.Z"

Step 7: Push

Ask the user before pushing:

Ready to push the release commit and tag to origin. Proceed?

If confirmed:

git push && git push --tags

Step 8: GitHub Release & Repo Metadata

After pushing, complete the release on GitHub:

1. Create a GitHub Release using gh release create:

   gh release create vX.Y.Z --title "Project Name vX.Y.Z" --notes "<release notes>"
   

   Use a condensed version of the RELEASE-NOTES.md entry — headline sections, changelog, key stats. Do not copy the entire file verbatim.

2. Update the repo description if any stats changed (skill count, phase count, etc.):

   gh repo edit OWNER/REPO --description "Updated description"
   

3. Verify both by checking the repo page:

   gh repo view OWNER/REPO --json description
   gh release view vX.Y.Z --repo OWNER/REPO
   

Do not skip this step. The GitHub Release is how users discover new versions, and the repo description is the first thing visitors see.

Conventional Commit Prefixes

Use these in the Full Changelog section:

Anti-Patterns