Add a /release skill to drive the release process

[zostay]

Adds .claude/skills/release/SKILL.md, a project skill that runs a release from changelog to published GitHub release, plus a pointer to it from CLAUDE.md.

The flow it encodes

Preflight on a clean, green master → pick the version by semver → set the Changes.md heading and date → match cmd/version.txt → push release/vX.Y.Z → open the release PR → wait on CI and fix what fails → triage the Copilot review → merge → tag vX.Y.Z → monitor release.yaml to publication → report.

What it documents beyond the happy path

The useful part of a release skill is the failure modes, so those are written down explicitly, each verified against the workflow files:

• The version comes from the ref name. Both release workflows run grep -Eo '[0-9]+\.[0-9]+\.[0-9]+.*$' over the branch or tag name, so release/v1.2.0 and v1.2.0 both yield 1.2.0. Get the branch name wrong and the version check fails on a value nobody typed.
• cmd/version.txt is matched by substring (grep -q), not equality.
• The Changes.md heading must be ## X.Y.Z YYYY-MM-DD exactly — two spaces — and the date must equal the day the workflow runs, in America/Chicago.
• The midnight problem. prepare.yaml checks that date when the branch is pushed and release.yaml checks it again when the tag is pushed. Those are separate runs, so a release that crosses midnight Central passes the first and fails the second, leaving a tag with no release. The skill covers both prevention and recovery.
• The heading must start with a digit. release.yaml builds the release notes by reading from the first ^## [0-9] line to the next, so a heading left as ## WIP would silently publish the previous version's notes.
• prepare.yaml and release.yaml share ten steps and test.yaml diffs them — editing one alone fails CI.
• A portable local preview of the exact notes that will be published, since the workflow's sed is GNU-only and fails on macOS BSD sed:

  awk '/^## [0-9]/{if(n++)exit;next} n' Changes.md

Copilot review handling

Copilot auto-reviews every PR here. The skill says to triage rather than obey: fix the small release-engineering-shaped findings (changelog typo, wrong version string) in the release PR, open issues for anything larger, and never block the release on a finding unless it is genuinely critical — and in that case stop and ask rather than abandoning the release alone.

Semver mapping

Tied to this changelog's existing emoji conventions: :boom: → major, :computer:/:sparkles: → minor, :hammer: and dependency bumps → patch. With the project past 1.0, any breaking change to an exported API or to command behavior is a major bump.

No code changes; nothing to test beyond CI.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds repository documentation for the release process by introducing a dedicated /release skill and linking to it from CLAUDE.md, so the release workflow (including failure modes) is captured in one repeatable, agent-runnable place.

Changes:

• Add .claude/skills/release/SKILL.md describing the end-to-end release procedure and common failure modes tied to the existing GitHub Actions workflows.
• Update CLAUDE.md to point maintainers at the new /release skill as the canonical driver for releases.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
CLAUDE.md	Adds a pointer to the /release skill as the documented release driver and highlights the key failure mode around date checks.
.claude/skills/release/SKILL.md	New skill doc encoding the full release process from changelog/version prep through tagging and monitoring the GitHub release workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zostay]

Addressed the Copilot finding in 8ad4021, though not as recommended.

Dropping ## WIP TBD from the skill would make it inaccurate — that is this repo's actual between-release convention (it was the Changes.md heading before #88, and step 12 of the skill offers to restore it for the next cycle). Removing it would leave the skill unable to describe the state it will most often find the file in.

But the finding did identify real ambiguity: two adjacent paragraphs, one listing ## WIP TBD as a heading state and the next warning that exact form publishes the wrong notes. Reworded so both forms stay documented while saying plainly that neither may survive into the release.