Release automation: a portable agent skill to drive the release flow (Claude Code + Codex/pi)

[minixalpha]

Background

Cutting a release currently means running a fixed sequence of mostly manual,
easy-to-misorder steps that span docs, GitHub, and PyPI. The pipeline already
automates the publish half (a v* tag triggers .github/workflows/release.yml
→ build → publish-to-pypi via OIDC Trusted Publishing → github-release),
but everything leading up to the tag, and all verification after it, is done by
hand. We want an agent skill to drive the whole flow end to end, with a
human gate at the right place.

Current release flow (steps the skill should drive)

1. Sync dev notes zh-CN → en — docs/dev_notes/zh-CN/X.Y.x.md is the
   hand-written source of truth; regenerate docs/dev_notes/en/X.Y.x.md from it.
2. Cut the changelog — move items out of [Unreleased] into a new
   ## [X.Y.Z] - YYYY-MM-DD section in docs/changelogs/X.Y.x.md
   (Keep a Changelog format).
3. Review / fix the PR description — make sure it accurately reflects the
   release.
4. ⛔ Human confirmation gate — after the PR description is fixed, stop and
   wait for the maintainer to confirm it's correct. Do not merge or
   proceed automatically.
5. Merge the PR (only after confirmation).
6. Push the vX.Y.Z tag — this is the version source of truth (version is
   derived from git tags via hatch-vcs); pushing the tag triggers the release
   workflow.
7. Watch the Release workflow — build → publish-to-pypi →
   github-release; report job status / surface failures.
8. Verify on PyPI — confirm the new version is live on the index.
9. Verify the GitHub Release — confirm the release + wheel/sdist assets and
   generated notes exist for the tag.
10. Smoke-test via uvx — e.g. uvx nanoPyCodeAgent@X.Y.Z ... to confirm
    the published artifact actually runs.

Proposal

Write a project-level agent skill that orchestrates the flow above.

• Portable across standard agents — should work for Claude Code and
  Codex / pi etc. Prefer a vendor-neutral layout (e.g. a SKILL.md /
  AGENTS.md-compatible definition committed to the repo) over anything tied to
  a single agent runtime.
• Human-in-the-loop is mandatory — the confirmation gate in step 4 is a hard
  requirement: the skill must pause after the PR description is fixed and only
  continue (merge + tag + verify) once the maintainer explicitly approves.

Notes / gotchas to bake into the skill

• The git tag is the version source of truth (hatch-vcs); keep
  pyproject.toml expectations, the changelog version, and the tag consistent.
• The release workflow's PyPI publish and GitHub release steps are idempotent
  (--check-url, gh release view || create), so re-running on failure is safe.
• When smoke-testing with uvx, a configured mirror can lag a few minutes
  behind PyPI, so a fresh version may not resolve immediately — the skill
  should either pin the official index or poll/retry before declaring success.