| name | cut-release |
| description | Cuts a new versioned release of claude-code-trace end-to-end without asking
any questions. Detects commits since the last ancestral tag, classifies them
with conventional-commit rules to pick the semver bump, bumps every
version-bearing file in sync, writes the CHANGELOG entry, commits and tags
on a release branch, pushes the tag to trigger the GitHub Actions release
pipeline, fast-forwards `main` onto the release commit and pushes it, then
cleans up the local branch. Use this skill whenever the user mentions
cutting, tagging, bumping, or shipping a release — including "cut a
release", "release v1.2.3", "tag and release", "bump version", "publish a
release", "do a patch release", or "make a new release". Trigger even when
the user does not name the version — the skill computes it. Also use
proactively when the user finishes a unit of work and asks to publish it.
|
Cut a Release — claude-code-trace
Turns "we should release this" into a tagged, pushed, pipeline-triggered, publicly
published release with a curated CHANGELOG, in a way that survives the project's strict
pre-commit hook chain and stays honest about what's actually shipping.
The skill is project-local because the steps depend on this repo's specific shape (three
version files, two lockfiles, GH Actions release on v* tag, the spec-drift +
test-reflection pre-commit hook pair).
Operating mode
The skill is fully automated end-to-end and fully synchronous. It never calls
AskUserQuestion, never waits for "yes", never branches on user preference, and
never runs any command in the background. Every Bash invocation runs in the
foreground so the session holds continuously from Phase 1 through Phase 9 — no
run_in_background: true, no trailing &, no nohup, no disown. This includes
long-running steps like gh run watch in Phase 7; set the Bash timeout parameter to
match the expected duration (e.g. 1800000 ms for the release pipeline) rather than
detaching.
Defaults are deterministic:
- Scope — always linear: every commit since
git describe --tags --abbrev=0 ships.
- Bump tier — highest conventional-commit tier in the subset (see
${CLAUDE_SKILL_DIR}/references/conventional-commits.md). BREAKING CHANGE: or !:
produces a minor bump while the version is 0.X.Y (pre-1.0 caveat) and a major
bump otherwise; the skill never silently promotes to 1.0.0.
- CHANGELOG — every Added/Fixed bullet is written from commit subjects + diff reads;
chore: / docs: / test: / ci: are always skipped.
- Push order — tag first, then main (so CI sees the tag immediately; main catches up
after).
The skill aborts (loudly) only on hard preconditions that would corrupt the release:
- Duplicate version — the proposed
vX.Y.Z tag already exists on origin. Abort
with Error: vX.Y.Z already exists on origin (commit <sha>). Refusing to release the same version twice. The user must delete the remote tag intentionally if they want a
re-release, or bump again.
- Dirty working tree — uncommitted changes the skill didn't create. Abort with a
list of dirty files.
npm run check fails — abort and surface the failure verbatim.
Before you start
Read these references on the first invocation in a session — they describe constants the
phase files refer to.
${CLAUDE_SKILL_DIR}/references/project-shape.md — version files, lockfiles, pre-commit
hooks, release pipeline wiring.${CLAUDE_SKILL_DIR}/references/conventional-commits.md — how commit prefixes map to
semver bump level.
${CLAUDE_SKILL_DIR}/references/changelog-template.md is loaded when you reach Phase 4.
Execution
Phase 1 — Inspect and decide
Read ${CLAUDE_SKILL_DIR}/steps/phase1-inspect-and-scope.md and follow all instructions.
Phase 2 — Build the release branch
Read ${CLAUDE_SKILL_DIR}/steps/phase2-build-release-branch.md and follow all instructions.
Phase 3 — Bump version files
Read ${CLAUDE_SKILL_DIR}/steps/phase3-bump-versions.md and follow all instructions.
Phase 4 — Write the CHANGELOG entry
Read ${CLAUDE_SKILL_DIR}/steps/phase4-changelog.md and follow all instructions.
Phase 5 — Verify, commit, tag
Read ${CLAUDE_SKILL_DIR}/steps/phase5-verify-commit-tag.md and follow all instructions.
Phase 6 — Push the tag (with duplicate-version preflight)
Read ${CLAUDE_SKILL_DIR}/steps/phase6-push-tag.md and follow all instructions.
Phase 7 — Watch the pipeline and verify the release is public
Read ${CLAUDE_SKILL_DIR}/steps/phase7-publish-github-release.md and follow all
instructions.
Phase 8 — Push the release commit to main
Read ${CLAUDE_SKILL_DIR}/steps/phase8-back-to-main.md and follow all instructions.
Phase 9 — Clean up
Read ${CLAUDE_SKILL_DIR}/steps/phase9-cleanup.md and follow all instructions.
What the skill will NOT do automatically
- Bypass pre-commit hooks with
--no-verify — always fix the underlying issue.
- Force-push (
git push -f) to main, the release tag, or any shared branch.
- Delete a remote tag or remote branch.
- Cut a major bump (
X.0.0) while the version is still 0.X.Y — pre-1.0 the skill
caps at minor even when a breaking change is detected.
- Re-tag an existing version — the duplicate-version preflight in Phase 6 aborts first.
The harness's auto-mode classifier may still intercept pushes to shared branches (e.g.
git push origin main) — that is out of skill scope. When it does, surface the error
and continue with the remaining phases; the user resolves the push themselves.
