Skill

Review

Audit score 70

release

boshu2/agentops

Validate and prepare releases: changelog, version bumps, tags, and exact-SHA CI verification.

What is release?

Automates release readiness checks, changelog generation from git history, semantic version bumps, and annotated tag creation. Use this when you're ready to move code from development to a tagged release—it handles pre-flight validation, generates release notes, and verifies the exact tagged SHA passes CI before declaring the release complete.

Pre-flight validation: tests, lint, clean tree, branch, and version checks
Generate changelog from git history with semantic classification (Added/Changed/Fixed/Removed)
Suggest semantic version based on commit analysis; confirm before proceeding
Detect and bump version strings across package files (package.json, pyproject.toml, etc.)
Create release commit and annotated git tag locally (reversible until push)
Generate curated release notes for GitHub Release page

How to install release

npx skills add https://github.com/boshu2/agentops --skill release

Claude Code

Cursor

Windsurf

Cline

How to use release

1.Run `/release --check` to validate your project is ready for release (tests pass, tree is clean, versions are consistent)
2.Run `/release` (no version) to let the agent suggest a semantic version based on recent commits, or run `/release X.Y.Z` with an explicit version
3.Review the generated changelog entry and version bumps; approve when ready
4.The agent creates a local release commit and annotated tag (no push yet)
5.Push the tag yourself: `git push origin main && git push origin vX.Y.Z`
6.After pushing, run the exact-SHA CI verification command provided by the agent to confirm the tagged SHA passes CI
7.Review the audit trail in `docs/releases/YYYY-MM-DD-vX.Y.Z-audit.md` to record the release evidence

Use cases

Good for

Cut a release after feature development: `/release 1.7.0` to generate changelog, bump versions, and create a tag ready to push
Validate release readiness without committing: `/release --check` to run pre-flight checks and report GO/NO-GO status
Update changelog only: `/release 1.7.0 --changelog-only` to refresh CHANGELOG.md without version bumps or tags
Dry-run a release: `/release 1.7.0 --dry-run` to preview changelog and version changes before writing
Verify a pushed release: after the user pushes the tag, run exact-SHA CI verification and reconciliation to confirm the release is green

Who it's for

Release engineers and maintainers preparing production releases
Project leads managing semantic versioning and changelog discipline
CI/CD operators verifying release artifacts and CI status before declaring a release complete

release FAQ

Does this skill push to GitHub or publish packages?

No. The skill prepares the release locally (changelog, version bumps, tag) and shows you the push command. You decide when to push. Publishing (npm, PyPI, etc.) and GitHub Release creation are handled by CI after you push the tag.

Can I undo a release if something goes wrong?

Yes, everything before the push is local and reversible: edit CHANGELOG.md, run `git reset HEAD~1` to undo the commit, or `git tag -d vX.Y.Z` to delete the tag. After you push, verify the exact-SHA CI run is green; if it fails, fix the issue and cut a newer release tag.

What if I want to update only the changelog without bumping versions or creating a tag?

Run `/release X.Y.Z --changelog-only` to update CHANGELOG.md only, with no version bumps, commit, or tag.

How does the skill suggest a semantic version?

It reads git history since the last tag, classifies commits as breaking/feature/fix, and suggests major/minor/patch accordingly. You confirm the version before it proceeds.

What happens after I push the tag?

Run the exact-SHA CI verification command the agent provides. It checks that the tagged SHA passed CI, runs `ao reconcile --json` to confirm release evidence, and records the run ID and status in the audit trail. The release is not complete until exact-SHA verification is green.

Full instructions (SKILL.md)

Source of truth, from boshu2/agentops.

name: release description: 'Run release validation. Triggers: "run release validation", "cut a release", "check release readiness".' practices:

continuous-delivery
gitops
supply-chain-integrity hexagonal_role: supporting consumes: [] produces:
result.json context_rel:
kind: supplier-to with: crank skill_api_version: 1 context: window: fork intent: mode: task sections: exclude:
- HISTORY intel_scope: full user-invocable: true metadata: tier: product dependencies: [] output_contract: CHANGELOG.md update, git tag, exact-SHA CI verdict handoff

Release Skill

Purpose: Take a project from "code is ready" to "tagged, pushed by the operator, and verified green on the exact tagged SHA."

Pre-flight validation, changelog from git history, version bumps across package files, release commit, annotated tag, curated release notes, and post-push exact-SHA CI verification. Local preparation is reversible. Publishing (including the GitHub Release page) is CI's job.

Quick Start

/release 1.7.0                # full release: changelog + bump + commit + tag
/release 1.7.0 --dry-run      # show what would happen, change nothing
/release --check               # readiness validation only (GO/NO-GO)
/release                       # suggest version from commit analysis

Arguments

Argument	Required	Description
`version`	No	Semver string (e.g., `1.7.0`). If omitted, suggest based on commit analysis
`--check`	No	Readiness validation only — don't generate or write anything
`--dry-run`	No	Show generated changelog + version bumps without writing
`--skip-checks`	No	Skip pre-flight validation (tests, lint)
`--changelog-only`	No	Only update CHANGELOG.md — no version bumps, no commit, no tag

Modes

Mode	Invocation	Behavior
Full Release	`/release [version]`	Pre-flight → changelog → release notes → version bump → user review → write → release commit → tag → push guidance → exact-SHA CI verification.
Check	`/release --check`	Pre-flight checks only; reports GO/NO-GO. Composable with `/validate`. No writes.
Changelog Only	`/release X.Y.Z --changelog-only`	Updates `CHANGELOG.md` only — no version bumps, no commit, no tag.

Workflow

Read references/release-workflow-detail.md for the full per-step procedure — bash commands, check tables, expected output, audit-record template, and worked examples. The index below is for orientation only; the agent must execute against release-workflow-detail.md for correctness.

Pre-flight — run scripts/ci-local-release.sh (blocking) plus version/lint/test/branch/changelog/SBOM/security checks. --check mode stops after this step.
Determine range — <last-tag>..HEAD. For non-HEAD cuts, see references/release-cut-and-bump.md.
Read git history — git log --oneline --no-merges <range> plus stats for ambiguity resolution.
Classify and group — Added / Changed / Fixed / Removed for CHANGELOG.md. Notes prose uses the richer 8-label set per references/release-notes.md.
Suggest version — major if breaking, minor if features, patch if only fixes. Confirm via AskUserQuestion.
Generate changelog entry — Keep-a-Changelog format, today's date, style-matched to the most recent existing entry.
Detect and offer version bumps — generic patterns (package.json, pyproject.toml, etc.) plus AgentOps-specific manifests per references/release-cut-and-bump.md.
User review — show generated changelog and version diffs; AskUserQuestion to proceed. --dry-run stops here.
Write changes — CHANGELOG.md update + version file edits.
Generate release notes — curated docs/releases/YYYY-MM-DD-v<version>-notes.md per references/release-notes.md. MUST be staged before the release commit.
Write audit trail — docs/releases/YYYY-MM-DD-v<version>-audit.md resolved via scripts/resolve-release-artifacts.sh. Format in workflow-detail Step 16.
Release commit — git commit -m "Release v<version>" with all release artifacts staged.
Tag — annotated git tag -a v<version> -m "Release v<version>".
GitHub Release (CI handles this) — do NOT gh release create locally; GoReleaser is sole creator.
Post-push exact-SHA CI verification — after the operator pushes, run scripts/verify-release-ci.sh v<version> and ao reconcile --json; do not declare the release complete until exact-SHA verification prints GO release-ci and reconciliation shows the latest release tag Validate as green or a newer tag explicitly supersedes an older failed tag.
Post-release guidance — show push commands and the verification command; do NOT push.
Audit trail format — see workflow-detail for the markdown template.

Boundaries

What this skill does

Pre-flight validation (tests, lint, clean tree, versions, branch)
Changelog generation from git history
Semver suggestion from commit classification
Version string bumps in package files
Release commit + annotated tag
Release notes (highlights + changelog) for GitHub Release page
Curated release notes for CI to publish on GitHub Release page
Post-release guidance plus exact-SHA CI verification instructions
Audit trail

What this skill does NOT do

No publishing — no npm publish, cargo publish, twine upload. CI handles this.
No building — no go build, npm pack, docker build. CI handles this.
No pushing — no git push, no git push --tags. The user decides when to push.
No CI triggering — the tag push (done by the user) triggers CI.
No monorepo multi-version — one version, one changelog, one tag. Scope for v2.

Everything this skill does is local and reversible:

Bad changelog → edit the file
Wrong version bump → git reset HEAD~1
Bad tag → git tag -d v<version>
Bad release notes → edit docs/releases/*-notes.md before push

Universal Rules

Don't invent — only document what git log shows
No commit hashes in the final output
No author names in the final output
Concise — one sentence per bullet, technical but readable
Adapt, don't impose — match the project's existing style rather than forcing a particular format
User confirms — never write without showing the draft first
Local only — never push, publish, or trigger remote actions
Not done at tag — after the user pushes, verify a green validate.yml run for the exact tagged SHA, run ao reconcile --json, and record the run id, conclusion, reconciliation overall status, and release-tag finding state in the handoff or release audit notes.
Supersede historical red tags deliberately — do not hand-wave an older failed tag Validate run. Either fix/rerun the tag pipeline when appropriate or cut a newer release tag whose ao reconcile release evidence is green.
Two audiences — CHANGELOG.md is for contributors (file paths, issue IDs, implementation detail). Release notes are for feed readers (plain English, user-visible impact, no insider jargon). Never copy-paste the changelog into the release notes.

Examples

User says: /release 1.7.0 Agent runs pre-flight → reads v1.6.0..HEAD git history → classifies commits → drafts CHANGELOG.md entry + curated release notes → detects version files (package.json, version.go, plugin manifests) → presents draft for review → on approval, writes files, creates release commit, creates annotated tag, prints push guidance, then after the user pushes verifies scripts/verify-release-ci.sh v1.7.0, runs ao reconcile --json, and records the run id/conclusion plus reconciliation state.

User says: /release --check Agent runs all pre-flight checks and outputs a GO/NO-GO summary table. No writes.

User says: /release (no version) Agent classifies commits and suggests a version (major if breaking, minor if features, patch if fixes only) with reasoning, then asks the user to confirm or override.

User says: /release 1.7.0 --dry-run Agent shows what the changelog entry + version bumps would look like, then stops without writing.

See references/release-workflow-detail.md for the full per-step example narration.

Troubleshooting

Problem	Cause	Solution
"No commits since last tag" error	Working tree clean, no new commits	Commit pending changes or skip release
Version mismatch warning	`package.json` and `go` version disagree	Manually sync before release, or pick one as source of truth
Tests fail during pre-flight	Breaking change not caught earlier	Fix tests, or use `--skip-checks` (not recommended)
Dirty working tree warning	Uncommitted changes present	Commit or stash before release
GitHub Release page body is empty	GoReleaser conflict with existing draft	CI deletes existing releases before GoReleaser runs; do NOT `gh release create` locally
`ci-local-release.sh` hangs on agents-hash	`~/.agents/patterns` is large	Set `AGENTS_HUB_OVERRIDE=/tmp/empty-hub` before invocation