| name | release |
| description | Create a new release by bumping versions, tagging, pushing, and generating release notes. Use when the user wants to release a new version. |
Release
Create a new versioned release of the project. This skill uses $SKILL_DIR/release.sh as the release engine.
Instructions
The user's input is in $ARGUMENTS (a semver version like 1.2.3 or v1.2.3, optionally followed by flags).
Flags
--dry-run: Perform all validation steps but make no changes. Report what would happen.--no-push: Create the commit and tag locally but do not push to remote.
Steps
-
Parse arguments: Extract the version from $ARGUMENTS. Strip any leading v prefix. If no version is provided, ask the user for one.
-
Validate version format: Must be valid semver (e.g., 0.1.0, 1.2.3, 2.0.0-beta.1).
-
Pre-flight validation:
- Run
git status --porcelain — if there are uncommitted changes, stop and tell the user to commit or stash first.
- Run
git fetch origin and verify local/remote are in sync.
- Check the tag doesn't already exist locally or on remote.
-
If --dry-run, stop here and report that validation passed.
-
Generate release notes from the commit history since the last tag:
git log $(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD --pretty=format:"- %s" --no-merges
Don't use these raw commit messages as the release notes. Instead, investigate what each commit/task actually did (read task files, check diffs) and write polished, user-facing release notes grouped by category (e.g., Features, Improvements, Bug Fixes, Documentation, Breaking Changes). Present the release notes to the user before proceeding.
-
Write the release notes to a file at /tmp/release-notes-X.Y.Z.md using the Write tool.
-
If --no-push, run the script without pushing:
echo "y" | $SKILL_DIR/release.sh --no-push --notes-file /tmp/release-notes-X.Y.Z.md X.Y.Z
Report what was created locally and stop.
-
Run the release script to handle the full release lifecycle:
echo "y" | $SKILL_DIR/release.sh --notes-file /tmp/release-notes-X.Y.Z.md X.Y.Z
The script has an interactive confirmation prompt — piping echo "y" auto-confirms it. The user already approved the release when they confirmed the release notes, so no second confirmation is needed. The script handles everything: version bumps, commit, tag, push, CI workflow monitoring, and applying release notes after CI creates the release.
-
Report success with the release tag and a link to the GitHub releases page.
Error Handling
- Fail fast on any error. Do not continue if a step fails.
- The release script has built-in rollback: if it fails after modifying version files but before pushing, it will automatically reset the commit and delete the local tag.
- Always provide clear, actionable error messages.
