docs(release): add a maintainer skill for cutting a release

[jd]

RELEASING.md documents the two-stage flow for a human driving the
Actions UI. This adds the agent-facing counterpart: the gh commands
for each stage, the pre-flight checks, and the guardrails.

It lives in .claude/skills/, not the published skills/ tree — that
one ships as the mergify plugin for CLI users, where a runbook for
releasing this repo would fire on anyone asking to release their own
project.

Content beyond what RELEASING.md already covers:

• Up front: there is no version to bump in any file, so no "release
  prep" PR. The workflow stamps the tag at build time.
• Pre-flight: main is green, no leftover draft, what ships since the
  last tag.
• Stage 2 is irreversible and outward-facing (immutable release, PyPI
  push), so the skill stops after the draft and requires an explicit
  go-ahead. Stage 1 is marked safe and repeatable.
• Post-publish verification of the Homebrew tap, which was undocumented:
  the homebrew-tap-sync workflow in Mergifyio/mergify-ci-bot opens a
  formula-bump PR against Mergifyio/homebrew-tap within ~20 min of
  publish, and it still needs a human to merge.

The why — GitHub's immutable-releases policy and the reason stage 1 runs
from workflow_dispatch — stays in RELEASING.md, which the skill
points at, so the two can't drift on the rationale.

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01RVKnCd4MKakhVJJiJTfZcD

[mergify]

Merge Protections

🔴 3 of 7 protections blocking · waiting on 👀 reviews and ⛓️ dependency

	Protection	Waiting on
🔴	⛓️ Depends-On Requirements	⛓️ dependency
🔴	👀 Review Requirements	👀 reviews
🔴	🔎 Reviews	👀 reviews
🟢	🤖 Continuous Integration	—
🟢	Enforce conventional commit	—
🟢	📕 PR description	—
🟢	🚦 Auto-queue	—

🔴 ⛓️ Depends-On Requirements

Waiting for

• depends-on=Mergifyio/mergify-cli#1796 [⛓️ fix(live-tests): use the admin token for the test-search smoke test #1796 [stack]]

This rule is failing.

Requirement based on the presence of Depends-On in the body of the pull request

• depends-on=Mergifyio/mergify-cli#1796 [⛓️ fix(live-tests): use the admin token for the test-search smoke test #1796 [stack]]

🔴 👀 Review Requirements

Waiting for

• #approved-reviews-by>=2

This rule is failing.

• any of:
  • #approved-reviews-by>=2
  • author = dependabot[bot]
  • author = mergify-ci-bot
  • author = renovate[bot]

🔴 🔎 Reviews

Waiting for

• #review-requested = 0

This rule is failing.

• #review-requested = 0
• #changes-requested-reviews-by = 0
• #review-threads-unresolved = 0

---

Show 4 satisfied protections

🟢 🤖 Continuous Integration

• all of:
  • check-success=ci-gate

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 📕 PR description

• body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

[Copilot]

🟢 Approval recommended

The change is isolated to documentation for maintainer operations and matches the referenced workflow structure without introducing code risk.

Pull request overview

Adds an agent-facing “releasing” skill runbook under .claude/skills/ that mirrors the existing human-driven RELEASING.md workflow, focusing on driving the two-stage GitHub Actions release process via gh while emphasizing safety guardrails around draft vs publish.

Changes:

• Introduces a new maintainer skill document for cutting a release using gh commands (pre-flight checks, stage 1 draft, stage 2 publish).
• Documents irreversible vs repeatable steps and enforces an explicit “go-ahead” before publishing.
• Adds post-publish verification steps, including the Homebrew tap sync PR flow.

File summaries

File	Description
.claude/skills/releasing/SKILL.md	Adds the agent-oriented release runbook (commands, guardrails, verification, recovery) aligned with the release.yml workflow.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jd]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	fix(live-tests): use the admin token for the test-search smoke test	#1796
2	docs(release): add a maintainer skill for cutting a release	#1795	👈

[jd]

Revision history

#	Type	Changes	Reason	Date
1	initial	7805be8		2026-09-04 12:59 UTC
2	rebase	7805be8 → 7e8ce16 (rebase only)	Rebased onto the live-tests token fix below it, so this PR's own live-tests run goes green. Diff unchanged.	2026-09-04 12:59 UTC

[jd]

Rebased onto #1796, which sits below this one in the stack now. The diff here is unchanged (7805be8 → 7e8ce16, compare — same single file, same content, new parent).

Why: live-tests was red here, and it had nothing to do with this docs-only diff. tests_show_no_match gets a 403 on GET /v1/ci/{owner}/repositories/{repo}/search/tests, on every PR in this repo, since Mergifyio/monorepo#39768 ("cut the ci application key down to least privilege") merged on 2026-09-03 08:40Z — the last green live-tests run was 2026-09-02 13:27Z. That change deliberately dropped search/tests from the ci key's scope, so the test was wrong to use the CI token. #1796 switches it to the admin token; putting it under this PR is what makes this PR's own live-tests run go green.