Release

This skill should be used when the user asks to "make a release", "create a release", "cut a release", "release a new version", "publish a release", or…

installs

stars

karma

view original SKILL.md from skills.shclick to expand

Release Workflow

This skill provides a systematic workflow for creating and publishing releases for the linear-cli project. It handles changelog management, version bumping, testing, and tagging.

When to Use

Use this skill when preparing to release a new version of linear-cli. The workflow ensures all changes are documented, tests pass, and versions are properly tagged before publishing.

Prerequisites

Ensure the following tools are available:

changelog skill for changelog management

svbump for version bumping (installed)

jj for version control operations

just for running the release tasks

jq for updating the Claude Code plugin versions

Release Workflow
Step 1: Review Commits Since Last Release

Determine the commits that have been made since the last release:

jj log --ignore-working-copy --git -r 'tags()..@' --no-graph

This shows all commits from the most recent tag to the current commit.

Step 2: Add Changelog Entries

For each commit identified above, evaluate whether it warrants a changelog entry. Focus on user-facing changes:

Include in changelog:

New features

Bug fixes

Breaking changes

Significant improvements

Deprecations

Exclude from changelog:

Internal refactoring without user impact

Documentation-only changes

Build/CI configuration changes

Chore commits (unless significant)

Use the changelog CLI to add entries. Use --attribute-pr with the commit SHA to automatically look up the associated PR and add attribution, excluding schpet and schpetbot:

changelog add --type <type> "<description>" --attribute-pr <commit-sha> --exclude-users schpet,schpetbot

Omit --attribute-pr for commits without an associated PR or when attribution isn't relevant.

Types match Keep a Changelog categories:

added - New features

changed - Changes in existing functionality

deprecated - Soon-to-be removed features

removed - Removed features

fixed - Bug fixes

security - Security improvements

Step 3: Verify Changelog with User

After adding all relevant changelog entries, show the unreleased section of CHANGELOG.md to the user and ask them to review it:

Read the CHANGELOG.md file

Show the [Unreleased] section

Ask: "Please review these changelog entries. Are there any changes needed before release?"

Make any requested adjustments

Step 4: Determine Semver Bump

Based on the types of changes in the changelog, determine and recommend the appropriate semantic version bump:

Major (X.0.0):

Breaking changes

Removed features

Significant API changes

Minor (0.X.0):

New features (added)

Deprecations

Backward-compatible functionality additions

Patch (0.0.X):

Bug fixes

Security fixes

Minor improvements with no new features

Present the recommendation to the user:

Based on the changelog entries, I recommend a <MAJOR/MINOR/PATCH> version bump because:
- [reason 1]
- [reason 2]

Current version: <current>
Proposed version: <proposed>

Should I proceed with this version bump?

Wait for user confirmation before proceeding.

Step 5: Run Changelog Release

Once the user confirms the version bump, run the changelog release command with the appropriate semver level:

changelog release <major|minor|patch>

This updates CHANGELOG.md, converting the Unreleased section to a versioned release.

Step 6: Execute Tag Process

After the changelog is released, run the tag recipe:

just tag

It does the whole release in order, stopping at the first failure:

Quality checks (just check): cargo fmt --all --check, cargo clippy --locked --workspace --all-targets -- -D warnings, and cargo test --locked --workspace

Version bump: writes the latest changelog version to workspace.package.version in Cargo.toml with svbump, then refreshes Cargo.lock with cargo update --workspace

Skill docs (just skill-docs): regenerates skills/linear-cli/SKILL.md and its references from the CLI's help

Plugin versions (just plugin-version): sets version in .claude-plugin/plugin.json and both version and plugins[0].version in .claude-plugin/marketplace.json

Commit and tag: jj commit -m "chore: Release linear-cli version <version>", then moves the main bookmark and sets the v<version> tag on that commit (@-)

Push: jj git push --bookmark main, then git push origin --tags

When it finishes it prints released v<version>.

Error Handling

If any step fails:

Quality checks fail: Fix the issues before continuing. Do not proceed with release if tests fail or linting errors exist.

Version bump fails: Verify the version format and files exist.

Push fails: Check authentication and remote access.

Always stop and report errors clearly. Never continue the release process if a critical step fails.

Important Notes

The justfile tag recipe runs every step above; there is no need to run them by hand

Use jj for all version control operations (per the project AGENTS.md)

Always use --ignore-working-copy for read-only jj operations

The workflow creates a commit on the parent (@-) and then creates a new working commit

Both jj git push and git push origin --tags are needed (jj for bookmark, git for tags)

Post-Release

After successful release:

Verify the tag appears on GitHub

Check that the GitHub Actions release workflow (.github/workflows/release.yml) builds the binaries and publishes the Homebrew formula and npm package

Confirm the new version is published

Reference

See the tag and plugin-version recipes in the justfile for the implementation.

don't have the plugin yet? install it then click "run inline in claude" again.

added explicit inputs section documenting github token and git config, expanded procedure with input/output for each step, formalized decision points for dry-run/check/error cases, specified output contract with file locations and urls, clarified outcome signals for each mode.

intent

this skill takes a project from "code is ready" to "tagged, pushed by the operator, and verified green on the exact tagged SHA." it handles pre-flight validation, changelog generation from git history, version bumps across package files, release commits, annotated tags, curated release notes, and post-push SHA verification. use it when you need to cut a release with confidence that every artifact is in sync and CI has signed off on the exact commit you tagged.

inputs

git repo: local git repository with clean working tree (no uncommitted changes)
package files: files containing version strings (package.json, setup.py, Cargo.toml, etc.) that need bumping
git history: commit log with conventional commit format (feat:, fix:, breaking:) for changelog generation
GitHub token: GITHUB_TOKEN environment variable with repo scope (required for GitHub Release creation and tag pushes)
git user config: user.name and user.email configured locally (git config user.name, git config user.email)
CI system access: the skill assumes a CI/CD system (GitHub Actions, GitLab CI, etc.) will verify the tagged SHA after push
version argument (optional): semantic version string (e.g., "1.7.0") or omitted to auto-suggest from commits

procedure

pre-flight validation
- input: git repo state
- check working tree is clean (no unstaged changes, no untracked files blocking release)
- check git user is configured
- check GITHUB_TOKEN env var is set and valid
- output: pass/fail status; if fail, list blocking issues
version determination
- input: optional version argument from user (e.g., "1.7.0")
- if version provided: use it
- if version omitted: analyze commit history since last tag, suggest next version using semver rules (breaking changes = major, new features = minor, fixes = patch)
- output: determined version string
changelog generation
- input: git commit history between last tag and HEAD, version string
- parse conventional commits (feat:, fix:, breaking:, etc.)
- group commits by type (features, fixes, breaking changes)
- output: formatted changelog text (markdown format)
version bump
- input: determined version, list of package files in repo
- locate version strings in each package file (e.g., "version": "1.6.0" in package.json)
- replace with new version
- output: modified package files (uncommitted)
release commit
- input: version-bumped package files, changelog
- stage all modified package files
- create commit with message: "chore: release 1.7.0" (with actual version)
- output: new commit on current branch (unpushed)
annotated tag
- input: new release commit, version string, changelog
- create annotated git tag named "v1.7.0" (with actual version)
- tag message: changelog text
- output: local annotated tag (unpushed)
publish to remote
- input: local commit, local tag, GITHUB_TOKEN
- push commit to remote branch (e.g., git push origin main)
- push tag to remote (e.g., git push origin v1.7.0)
- create GitHub Release page via GitHub API using tag and changelog
- output: commit and tag live on GitHub, Release page created
CI verification trigger
- input: pushed tag, CI webhook configuration
- CI system automatically detects tag push and runs full test suite on exact tagged SHA
- skill does not wait for CI; CI completion is operator's responsibility to verify
- output: CI job triggered (link provided to operator)

decision points

if --dry-run flag provided: execute steps 1-6 (pre-flight, version, changelog, bump, commit, tag) but do not execute step 7 (publish). show operator what would be created. allow rollback by discarding local commits and tags.
if --check flag provided: execute step 1 (pre-flight validation) only. return GO (all checks pass) or NO-GO (blocking issues). do not modify any files or git state.
if no version argument and no commits since last tag: suggest patch bump and continue; do not fail.
if package files missing or unparseable: fail with clear error listing which files could not be updated. operator must fix before retry.
if GITHUB_TOKEN invalid or missing: fail at step 7 pre-push validation. do not push commit or tag. operator must set valid token and retry (local commit and tag are preserved for reuse).
if working tree dirty: fail at pre-flight. operator must stash or commit changes before release can proceed.
if remote push fails (network timeout, rate limit, permissions): catch error, do not create GitHub Release, output error with retry guidance. local commit and tag remain; operator retries push manually.
if changelog or version bump produces merge conflicts: unlikely in normal workflow, but if package files were edited on another branch, fail with conflict details. operator resolves and retries.

output contract

dry-run output: formatted text showing (a) version to be released, (b) changelog to be included, (c) package files that would be modified, (d) commit message, (e) tag name and tag message. no files written; git state unchanged.
check output: simple GO or NO-GO with list of failed checks (if any). no files written; git state unchanged.
full release output: (a) local commit on current branch with bumped versions, (b) local annotated tag with changelog in tag message, (c) pushed commit and tag on GitHub, (d) GitHub Release page created with changelog, (e) CI job triggered on tagged SHA. all artifacts use consistent version string (e.g., "1.7.0" or "v1.7.0" for tag).
file locations: modified package files in their original locations (e.g., ./package.json, ./setup.py). git objects and refs live in .git/. GitHub Release page at https://github.com/{owner}/{repo}/releases/tag/v{version}.

outcome signal

pre-flight pass: "pre-flight check: GO. ready to release."
version suggested: "no version provided. suggest 1.7.0 based on commits. run /release 1.7.0 to proceed."
dry-run displayed: "dry-run: 0 files modified, 1 commit created, 1 tag created. no push. run /release 1.7.0 to publish."
release complete: "released 1.7.0. pushed to github. tag v1.7.0 created. release page: https://github.com/owner/repo/releases/tag/v1.7.0. ci job running at [link]."
error state: clear error message specifying the step that failed (e.g., "version bump failed: could not parse version in ./package.json") and how to recover.
operator verification: operator navigates to GitHub to confirm (a) commit is live on main, (b) tag exists and points to correct commit, (c) Release page is published, (d) CI is running or completed on tagged SHA.