hs-release — Claude Code skill for Hindsight releases
The hs-release Claude Code skill cuts a core Hindsight release and prepares a separate changelog and blog PR. It activates for requests to start a release, change the version, or publish a new Hindsight version.
MIT 110 installs ★ 62,471 updated 2026-10-24
npx skills add vectorize-io/hindsight --skill hs-release -a claude-codeWhat hs-release does
The skill releases the core Hindsight version from the latest main. It runs ./scripts/release.sh <version>, which updates component versions, regenerates the OpenAPI spec and client SDKs, then commits, tags, and pushes directly to main. This push cannot be undone and triggers GitHub Actions to publish packages to PyPI, npm, and Helm. The fixes for the release must already be merged to main.
Once the tag exists, the skill creates a separate branch for a changelog and blog PR. It generates the changelog with uv run --directory hindsight-dev generate-changelog <version>, which requires OPENAI_API_KEY. It also refreshes the changelog copy in the docs skill and checks blog formatting with npx prettier --check <blog file>. Integrations have independent versions and are outside this release flow.
What it helps with
- cut a new core Hindsight release
- bump component and client SDK versions
- generate a changelog between release tags
- prepare a PR with release notes and a blog post
Example prompts for the agent
- Cut Hindsight version 0.8.1.
- Start a Hindsight release at version 0.8.1.
- Prepare the changelog and blog post for the next Hindsight release.
How to install hs-release
1Skills CLI (Vercel)
npx skills add vectorize-io/hindsight --skill hs-release -a claude-code2Manually: put the files in place
~/.claude/skills/hs-release/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hs-release/
1Skills CLI (Vercel)
npx skills add vectorize-io/hindsight --skill hs-release -a codex2Manually: put the files in place
.agents/skills/hs-release/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vectorize-io/hindsight --skill hs-release -a cursor2Manually: put the files in place
.cursor/skills/hs-release/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vectorize-io/hindsight .claude/skills/hs-release2Manually: put the files in place
.github/skills/hs-release/SKILL.md1Skills CLI (Vercel)
npx skills add vectorize-io/hindsight --skill hs-release -a gemini-cli2Platform CLI
gemini skills install https://github.com/vectorize-io/hindsight --path .claude/skills/hs-releaseManually: put the files in place
.devin/skills/hs-release/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vectorize-io/hindsight --skill hs-release -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about hs-release
How do I install hs-release in Claude Code?
Run npx skills add vectorize-io/hindsight --skill hs-release -a claude-code. The skill is installed at ~/.claude/skills/hs-release/SKILL.md.
What does hs-release do?
It cuts a core Hindsight release by pushing a commit and tag straight to main, then prepares a separate PR for the changelog and blog post. Integrations use independent versions.
What does hs-release need to run?
Changelog generation requires OPENAI_API_KEY. The release push to main triggers package publishing to PyPI, npm, and Helm.
Source text
SKILL.md · MIT
--- name: hs-release description: Cut a core Hindsight release (vX.Y.Z) and open the changelog + blog PR. Use when asked to cut/start a release, bump the version, or publish a new Hindsight version. user_invocable: true --- # Hindsight Release Cut a **core** Hindsight release and open the accompanying changelog/blog PR. This is for the core product version (API, clients, CLI, control plane, Helm). **Integrations are versioned independently** — use `scripts/release-integration.sh` for those, not this skill. The release is **irreversible and outward-facing**: it tags a version and pushes it straight to `main`, which triggers CI that publishes packages to PyPI / npm / Helm. Confirm the version number and that the intended fixes are already merged to `main` before you start. ## Step 0 — Pre-flight 1. **Decide the base.** A release is cut from the latest `origin/main`, never from a feature branch. `git fetch origin --tags` first. Confirm the "couple of fixes" the user means are actually merged to `main` (`git log v<prev>..origin/main --oneline`). 2. **Find where `main` is checked out.** `main` is often already checked out in a sibling worktree (`git worktree list`). You **cannot** check out `main` in a second worktree — run the release in the worktree that already holds it. If that worktree is dirty with throwaway cruft (`.next-*` tsconfig paths, screenshots), `git stash push -u`, fast-forward to `origin/main`, run the release, then `git stash pop`. 3. **Pitfall:** never pipe the checkout in an `&&` chain like `git checkout main 2>&1 | tail && git reset --hard ...` — the pipe's exit status is `tail`'s (always 0), so a failed checkout won't stop the chain and the `reset` fires on the **wrong branch**. Check out as its own command and verify `git branch --show-current` before resetting. ## Step 1 — Cut the release Run from the worktree on a clean `main`: ```bash ./scripts/release.sh <version> # e.g. 0.8.1 (no leading v) ``` `release.sh` bumps the version in every component, regenerates the OpenAPI spec + all client SDKs, updates docs versioning, commits `Release v<version>`, tags `v<version>`, and **pushes the commit and tag directly to `main`**. The push triggers the `Release` GitHub Actions workflow that builds and publishes the packages. It is **not** a PR. Verify after: `gh run list --limit 5` should show the `Release v<version>` workflow running, and `git ls-remote --tags origin v<version>` should return the tag. ## Step 2 — Changelog + blog PR (separate) Done **after** the tag exists, as its own PR (precedent: v0.8.0 = #2053, v0.8.1 = #2080). Work on a branch off the new `main`: ```bash git checkout -b docs-changelog-<version> origin/main ``` Only spin up a separate worktree (`git worktree add ../hindsight-changelog-<version> -b docs-changelog-<version> origin/main`) if you can't get a clean checkout otherwise — e.g. `main` is held in another worktree and the current one has work you don't want to disturb. **Branch naming:** use the `docs-` (hyphen) convention, e.g. `docs-changelog-0.8.1`. A remote branch literally named `docs` exists, so any `docs/...` branch is rejected on push with `directory file conflict`. ### Changelog ```bash uv run --directory hindsight-dev generate-changelog <version> ``` LLM-summarizes the commits between the previous tag and `v<version>` and prepends an entry to `hindsight-docs/src/pages/changelog/index.md`. The entry ends with a **Database Migrations** section listing every Alembic migration added in the range, each linking to the PR that introduced it. That section is enumerated deterministically from git (`--diff-filter=A` over `hindsight_api/alembic/versions/`), not by the LLM — don't hand-edit it, and if a migration is missing, check that its commit actually added the file in the tag range. Requires `OPENAI_API_KEY` (already in the repo `.env`). It excludes `hindsight-integrations/` source, but new integrations whose commits also touched docs will still appear — that matches precedent, leave them in the **changelog**. ### Blog post Hand-write `hindsight-docs/blog/YYYY-MM-DD-version-X-Y-Z.md` (mirror an existing one; patch releases are short — see `2026-06-02-version-0-7-2.md`). Guidance: - **Explain user impact, not internals/mechanism.** Lead with what the user can now do and what to set. Config/env-var names are fine (developer-facing), code symbols and internals are not. - **Do not list integrations in the release blog.** The core blog covers core engine / API / ops changes; each integration ships its own changelog. (Integrations may still appear in the generated `changelog/index.md` — that's fine; just keep them out of the blog.) - Call out an upgrade recommendation when there are operational/data-integrity fixes. - Validate formatting: `npx prettier --check <blog file>`. ### Sync the docs skill ```bash ./scripts/generate-docs-skill.sh ``` Refreshes `skills/hindsight-docs/references/changelog/index.md`. It will also bump `skills/hindsight-docs/references/openapi.json` by one version — `release.sh` regenerates the skill *before* bumping OpenAPI, so the skill copy lags a version in the release commit; this step syncs it. Expect a one-line `version` diff there; keep it. ### Commit, push, PR ```bash git add -A git commit --no-verify -m "docs: changelog and blog post for v<version>" git push -u origin docs-changelog-<version> gh pr create --base main --title "docs: changelog and blog post for v<version>" --body "..." ``` Expected files in the PR: the changelog entry, the new blog post, the regenerated skill changelog mirror, and the skill `openapi.json` version sync. ## Cleanup If you created a temporary worktree, remove it once the PR is up (`git worktree remove ../hindsight-changelog-<version>`; the branch stays on origin). Restore any stash you popped in Step 0.
© vectorize-io · MIT · vectorize-io/hindsight