release-sidecar — Claude Code skill: what it does, how to install
release-sidecar walks a sidecar release from version pick to a published Homebrew formula: semver tag, dependency pins, changelog, GoReleaser build.
MIT 1 installs ★ 1,095 updated 2026-10-08
npx skills add marcus/sidecar --skill release-sidecar -a claude-codeWhat release-sidecar does
This skill encodes how sidecar gets released. The short path is a single make target that reads the next version off the latest tag, rewrites the changelog heading, commits, pushes and tags, then leaves the rest to CI. You either pass BUMP or set RELEASE_VERSION=vX.Y.Z yourself.
Around it sit the checks. A preflight script queries gh run list --workflow=go-ci.yml and refuses to continue when tests or lint are red, still running, or missing. make sync-deps moves every github.com/marcus/* requirement to its newest tag, and the snapshot and dry-run targets show the plan without changing anything. Tag push fires verify, the GoReleaser release, and the tap job that turns packaging/homebrew/sidecar.rb.tmpl into Formula/sidecar.rb.
Come prepared: Go matching your go.mod, a clean tree with main level with origin/main, an authenticated gh allowed to push to marcus/homebrew-tap, the HOMEBREW_TAP_TOKEN secret on the repo, and no replace lines in go.mod. Keep the workspace file in mind, because go.work points sibling imports at local checkouts and a stale pin hides there; both the gate and the sync run with GOWORK=off.
What it helps with
- cut a sidecar release with one make target instead of replaying a checklist
- confirm Go CI is green on the commit about to be tagged
- pin sibling
github.com/marcus/*modules to their newest tags - finish only the Homebrew tap step when the tag already exists
- check the published version installs into a throwaway
GOBIN
Example prompts for the agent
- Prep the sidecar release and tell me which
BUMPto use - Start with a dry run:
make release-dry-run BUMP=minor - The tag already exists, so finish just the tap:
RELEASE_VERSION=vX.Y.Z make release-tap
How to install release-sidecar
1Skills CLI (Vercel)
npx skills add marcus/sidecar --skill release-sidecar -a claude-code2Manually: put the files in place
~/.claude/skills/release-sidecar/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/release-sidecar/
1Skills CLI (Vercel)
npx skills add marcus/sidecar --skill release-sidecar -a codex2Manually: put the files in place
.agents/skills/release-sidecar/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add marcus/sidecar --skill release-sidecar -a cursor2Manually: put the files in place
.cursor/skills/release-sidecar/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install marcus/sidecar .claude/skills/release-sidecar2Manually: put the files in place
.github/skills/release-sidecar/SKILL.md1Skills CLI (Vercel)
npx skills add marcus/sidecar --skill release-sidecar -a gemini-cli2Platform CLI
gemini skills install https://github.com/marcus/sidecar --path .claude/skills/release-sidecarManually: put the files in place
.devin/skills/release-sidecar/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add marcus/sidecar --skill release-sidecar -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 release-sidecar
How do I install release-sidecar in Claude Code?
Run npx skills add marcus/sidecar --skill release-sidecar -a claude-code. The skill file ends up at ~/.claude/skills/release-sidecar/SKILL.md.
What does release-sidecar do?
It carries a sidecar release through: semver version choice, dependency updates, changelog stamping, GoReleaser publishing and the Homebrew formula refresh, plus a check that the result installs.
Why does every step insist on GOWORK=off?
With go.work active, sibling modules resolve to local checkouts, so an outdated pin stays out of sight. The preflight gate and make sync-deps both run with the workspace switched off.
Source text
SKILL.md · MIT
--- name: release-sidecar description: Release new versions of sidecar. Covers version tagging with semver, td dependency updates, go.mod validation, CHANGELOG updates, GoReleaser automation, Homebrew tap updates, and verification steps. Use when preparing or executing a release. disable-model-invocation: true --- # Releasing a New Version Operator contract: **`docs/guides/active/releasing.md`**. Enforcement lives in `scripts/` and `BUMP=minor make release` (or `RELEASE_VERSION=vX.Y.Z make release` for an explicit version). Prefer the one-shot command over replaying this checklist by hand. ## Prerequisites - Go matching `go.mod` - Clean working tree; `main` identical to live `origin/main` - Tests and **Go CI** green on the commit you will tag (tests *and* lint) — `check-release-state.sh` now checks this itself via `gh run list --workflow=go-ci.yml` and fails closed if it's red/running/missing, so you don't have to remember to look - GitHub CLI authenticated with push access to `marcus/homebrew-tap` - No `replace` directives in `go.mod` - `HOMEBREW_TAP_TOKEN` secret present in the GitHub repo (CI tap job) **Beware of go.work**: always use `GOWORK=off` when updating dependencies and when validating install paths. Local lint must match CI's golangci-lint **v2.12.2**, or trust CI: ```bash gh run list --workflow=go-ci.yml --limit=1 ``` ## Prepare (sidecar-specific) ### 1. Version ```bash git tag -l 'v*' | sort -V | tail -1 ``` SemVer: major / minor / patch as usual. ### 2. Sibling dependencies (td, tasks) ```bash make sync-deps # pins every github.com/marcus/* requirement to its latest tag ``` `check-release-state.sh` enforces this and refuses to tag when one is behind. `go.work` resolves those imports to the local checkouts, so drift is invisible locally — both the gate and `sync-deps` use `GOWORK=off`. If a sibling jumped several minors, decide deliberately (pin for a focused release vs take latest and note it under Dependencies) and smoke its tab in the app. ### 3. CHANGELOG ```markdown ## [Unreleased] ### Features - … ### Bug Fixes - … ### Dependencies - … ``` Commit the changelog (and any dependency bump) on `main`, then push so `HEAD == origin/main`. Leave the heading as `## [Unreleased]` — `make release` stamps it to `## [vX.Y.Z] - YYYY-MM-DD` for you. ## Publish ```bash # Dry-run (optional but recommended for tooling changes) make release-snapshot ./scripts/verify-release-archives.sh dist ./scripts/test-release-guards.sh dist ./scripts/test-release-publication.sh make release-dry-run BUMP=minor # prints the derived version + plan, no mutation # Cut the release: derive the version, stamp the changelog, commit, push, # then the fail-closed preflight → tag → CI → formula verify/publish BUMP=minor make release ``` The version is stated exactly once — via `BUMP` derived from the latest tag, or by setting `RELEASE_VERSION=vX.Y.Z` yourself (also works if you stamped the CHANGELOG heading by hand). `scripts/release.sh` refuses an empty `[Unreleased]` section, a tree dirty beyond `CHANGELOG.md`, a tag that already exists, and a `RELEASE_VERSION` that contradicts an already-stamped heading, before handing off to `scripts/publish-release.sh`. What it enforces and does end to end is documented in `docs/guides/active/releasing.md`. Resume only the tap step if the tag/release already exists: ```bash RELEASE_VERSION=vX.Y.Z make release-tap ``` ### CI jobs (on tag push) 1. **`verify`** — tag points at live `main`, tests, snapshot archives, release guards 2. **`release`** — GoReleaser publishes GitHub release + binaries 3. **`update-homebrew-tap`** — renders `packaging/homebrew/sidecar.rb.tmpl` and pushes `Formula/sidecar.rb` with downgrade/idempotency/race guards td/nightshift formulas are **not** auto-bumped; edit them by hand when co-releasing. ## Verify ```bash gh run list --workflow=release.yml --limit=1 gh release view vX.Y.Z --json assets -q '.assets[].name' GOBIN=$(mktemp -d) GOWORK=off go install github.com/marcus/sidecar/cmd/[email protected] "$GOBIN/sidecar" --version ``` `go install @vX.Y.Z` can 500 from the checksum DB for a minute or two after the tag — wait and retry. Prefer a throwaway `GOBIN` so verification does not clobber a dev machine's `sidecar`. ## Dev machine after release ```bash # Return to the canonical main development build: make install-local # Or keep the released Homebrew build active: make use-homebrew # In either case, prove the managed link and both login-shell modes: make install-status ``` ## Recovery Prefer a new patch release. Keep tags. Resume tap with `make release-tap`. See `docs/guides/active/releasing.md`. ## Checklist - [ ] Go CI green (tests + lint) on the commit to tag — enforced automatically by `check-release-state.sh` - [ ] Working tree clean; `main` == `origin/main` - [ ] td bump considered; td tab smoke if td moved - [ ] No `replace` in go.mod; `GOWORK=off` build works - [ ] Agent integration assets: if any bundled asset's bytes changed, its version constant, `internal/agentlifecycle/capabilities.json`, and the golden in `internal/agentintegration/asset_golden_test.go` all moved with it (the golden test fails if they did not) - [ ] CHANGELOG bullets under `## [Unreleased]` - [ ] `BUMP=minor make release` (or `RELEASE_VERSION=vX.Y.Z make release`) succeeded - [ ] Release assets present; formula URL/sha match (automatic) - [ ] `go install` verified into throwaway `GOBIN` - [ ] `make install-status` proves the dev machine is on the intended binary
© marcus · MIT · marcus/sidecar