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:

Change Type	Bump	Examples
Breaking API/behavior changes	Major (X.0.0)	Removed feature, renamed public API, changed data format
New features, new phases, new skills	Minor (x.Y.0)	Added skill, added phase, new capability
Bug fixes, typos, doc updates, refactors	Patch (x.y.Z)	Fixed typo, corrected phase number, updated docs

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:

File	Fields to update
.claude-plugin/plugin.json	.version
.claude-plugin/marketplace.json	.metadata.version AND .plugins[].version
.cursor-plugin/plugin.json	.version (if exists)
.codex/plugin.json	.version (if exists)
package.json	.version
Cargo.toml / pyproject.toml	version field

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:

Prefix	Meaning
feat:	New feature or capability
fix:	Bug fix
refactor:	Code restructuring without behavior change
docs:	Documentation only
chore:	Build, CI, dependencies, tooling
perf:	Performance improvement
test:	Test additions or fixes
style:	Formatting, whitespace (no logic change)

---

Anti-Patterns

Mistake	Fix
Releasing without running tests	Always run tests in Step 1
"Bump version" as the commit message	Use release: vX.Y.Z — [summary]
Adding AI co-authorship	The user is the author. Period.
Dumping raw git log as release notes	Write narrative release notes that a human would want to read
Skipping the tag	Tags are how users and tools identify releases
Force-pushing a release	Never. If something is wrong, cut a new patch release.
Releasing from a feature branch	Releases come from main unless the user explicitly confirms otherwise
Pushing the tag but not creating a GitHub Release	Always create a GitHub Release — it's how users find new versions
Forgetting to update the repo description	If stats changed (skill count, phase count), update the About section