release

Name: release
Availability: InStock
Author: tobi

Manage releases for this project. Validates changelog, installs git hooks, and cuts releases. Use when user says "/release", "release 1.0.5", "cut a release",…

view source

installs

stars

karma

view original SKILL.md from skills.shclick to expand

Release

Cut a release, validate the changelog, and ensure git hooks are installed.

Usage

/release 1.0.5 or /release patch (bumps patch from current version).

Process

When the user triggers /release <version>:

Gather context — run skills/release/scripts/release-context.sh <version>.
This silently installs git hooks and prints everything needed: version info,
working directory status, commits since last release, files changed, current
[Unreleased] content, and the previous release entry for style reference.

Commit outstanding work — if the context shows staged, modified, or
untracked files that belong in this release, commit them first. Use the
/commit skill or make well-formed commits directly.

Write the changelog — if [Unreleased] is empty, write it now using
the commits and file changes from the context output. Follow the changelog
standard below. Re-run the context script after committing if needed.

Cut the release — run scripts/release.sh <version>. This renames
[Unreleased] → [X.Y.Z] - date, inserts a fresh [Unreleased],
bumps package.json, commits, and tags.

Show the final changelog — print the full [Unreleased] +
minor series rollup via scripts/extract-changelog.sh <version>.
Ask the user to confirm before pushing.

Push — after explicit confirmation, run git push origin main --tags.

Watch CI — after the push, start a background dispatch to watch the
publish workflow. Use interactive_shell in dispatch mode with:

gh run watch $(gh run list --workflow=publish.yml --limit=1 --json databaseId --jq '.[0].databaseId') --exit-status

The agent will be notified when CI completes and should report the result.

Check dependency updates — before cutting the release, check for
updates to sqlite-vec (and platform packages), node-llama-cpp,
and better-sqlite3. Run pnpm outdated and report any available
updates for these packages. If updates exist, bump them (pinned, no
^ ranges) and re-run tests before proceeding.

If any step fails, stop and explain. Never force-push or skip validation.

Dependency Policy

All dependencies must be pinned to exact versions (no ^ or ~ ranges).
The lockfile ensures reproducible installs. When adding or updating any
dependency, always use the exact version string (e.g. "3.18.1" not
"^3.18.1").

Changelog Standard

The changelog lives in CHANGELOG.md and follows Keep a Changelog conventions.

Heading format

## [Unreleased] — accumulates entries between releases

## [X.Y.Z] - YYYY-MM-DD — released versions

Structure of a release entry

Each version entry has two parts:

1. Highlights (optional, 1-4 sentences of prose)

Immediately after the version heading, before any ### section. The elevator
pitch — what would you tell someone in 30 seconds? Only for significant
releases; skip for small patches.

## [1.1.0] - 2026-03-01

QMD now runs on both Node.js and Bun, with up to 2.7x faster reranking
through parallel contexts. GPU auto-detection replaces the unreliable
`gpu: "auto"` with explicit CUDA/Metal/Vulkan probing.

2. Detailed changelog (### Changes and ### Fixes)

### Changes

- Runtime: support Node.js (>=22) alongside Bun. The `qmd` wrapper
  auto-detects a suitable install via PATH. #149 (thanks @igrigorik)
- Performance: parallel embedding & reranking — up to 2.7x faster on
  multi-core machines.

### Fixes

- Prevent VRAM waste from duplicate context creation during concurrent
  `embedBatch` calls. #152 (thanks @jkrems)

Writing guidelines

Explain the why, not just the what. The changelog is for users.

Include numbers. "2.7x faster", "17x less memory".

Group by theme, not by file. "Performance" not "Changes to llm.ts".

Don't list every commit. Aggregate related changes.

Credit contributors: end bullets with #NNN (thanks @username) for
external PRs. No need to credit the repo owner.

What not to include

Internal refactors with no user-visible effect

Dependency bumps (unless fixing a user-facing bug)

CI/tooling changes (unless affecting the release artifact)

Test additions (unless validating a fix worth mentioning)

GitHub Release Notes

Each GitHub release includes the full changelog for the minor series back
to x.x.0. The scripts/extract-changelog.sh script handles this, and the
publish workflow (publish.yml) calls it to populate the GitHub release.

Git Hooks

The pre-push hook (scripts/pre-push) blocks v* tag pushes unless:

package.json version matches the tag

CHANGELOG.md has a ## [X.Y.Z] - date entry for the version

CI passed on GitHub (warns in non-interactive shells, blocks in terminals)

Hooks are installed silently by the context script. They can also be installed
manually via skills/release/scripts/install-hooks.sh or automatically via
bun install (prepare script).

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.