agentleFS
hhopkehhopke/intervals-icu-mcp/.claude/skills/release-write/SKILL.md

release-write

Skill121 starsChanged 9 days agoMITView on GitHub

Cut a new release. Use when the user wants to ship a tagged release. Previews the version bump from merged PR titles, dispatches the Publish Release workflow (tests + draft GitHub Release), writes user-facing release notes into the draft, and hands it to the maintainer to publish. Publishing the draft tags it and publishes to PyPI + MCP Registry.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Publishing is the maintainer's call: Never publish the draft without the user's explicit go-ahead for that specific release.

    line 37
  2. Very specific:

    No draft release is pending: gh release list --limit 5 (a leftover draft makes the dispatch fail in draft-release.

    line 47
  3. Very specific:

    If next_version.py says there is nothing to release, stop.

    line 65
  4. Distinctive:

    Wait for the user's explicit go-ahead with the final version.

    line 69
  5. Distinctive:

    Start the watch in the background and write the notes (step 4) while the tests run:

    line 76
  6. Very specific:

    If it fails, surface gh run view <id> --log-failed and stop.

    line 82
  7. Very specific:

    Read the body, and the diff (gh pr diff N) when the body doesn't say what changed for a user.

    line 93
  8. Very specific:

    Tool counts: only when tools were added or removed.

    line 122
  9. Distinctive:

    Write the notes to a file in the scratchpad, show them to the user, and revise until they're happy.

    line 126
  10. Distinctive:

    Don't dispatch again: with no commits past the new tag it reports "Nothing to release".

    line 153

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Context

Releases are cut on demand (no schedule), in two steps. CHANGELOG.md is frozen at 5.8.0; release notes live only in GitHub Releases.

Step 1 — dispatch (.github/workflows/publish.yml, workflow_dispatch):

JobDoes
preflightFails fast: requires main, checks the server.json description is ≤ 100 chars, computes the version with .github/scripts/next_version.py (fails on "nothing to release")
testFull test suite (reusable test.yml)
draft-releaseRefuses if any draft release already exists, then creates a draft Release vX.Y.Z pinned to the tested commit, with GitHub's generated notes (PR titles) as a placeholder. No tag yet, nothing published

Step 2 — publish (the maintainer publishes the draft → release: published):

JobDoes
pypiBuilds at the new tag and publishes to PyPI
mcp-registrySyncs server.json to the tag version and publishes to the MCP Registry
verifyPolls PyPI and the MCP Registry until both serve the version, then smoke-tests a clean uvx install and import of it

Version bump, highest wins across all commits since the last tag: ! → major, feat → minor, anything else → patch. Don't tag or create the release by hand, and don't add a chore(release) commit.

Publishing is the maintainer's call. Never publish the draft without the user's explicit go-ahead for that specific release. If they ask you to, use gh release edit vX.Y.Z --draft=false (it runs under their own login, so it triggers the publish jobs; a GITHUB_TOKEN publish would not).

Instructions

1. Preflight

  • On main, up to date with origin/main, tags fetched (git fetch origin main --tags).
  • make can-release is green (or run /release-check).
  • No draft release is pending: gh release list --limit 5 (a leftover draft makes the dispatch fail in draft-release; ask the user whether to publish or delete it).

2. Preview the version

python3 .github/scripts/next_version.py
git log --oneline --no-merges "$(git describe --tags --abbrev=0 --match 'v[0-9]*')"..HEAD

Show the user the computed version and the bump each commit asks for. Flag:

  • a non-conventional subject (counts as a patch);
  • a type that doesn't match the change: a user-facing addition or a response-shape change titled fix/chore (should have been feat, so the bump is too small), or a breaking change per CLAUDE.md without ! (should be a major). Check the PR (gh pr view N) when the subject alone is ambiguous. If the computed version is wrong, propose an explicit override.

If next_version.py says there is nothing to release, stop.

3. Confirm, then dispatch

Wait for the user's explicit go-ahead with the final version. Then:

gh workflow run publish.yml --ref main                    # computed version
gh workflow run publish.yml --ref main -f version=X.Y.Z   # explicit override

Start the watch in the background and write the notes (step 4) while the tests run:

gh run watch "$(gh run list --workflow=publish.yml --event=workflow_dispatch --limit=1 --json databaseId --jq '.[0].databaseId')" --exit-status

If it fails, surface gh run view <id> --log-failed and stop. Nothing was tagged or published, so the fix is: fix on main, delete any draft it left, dispatch again.

4. Write the release notes

Gather every PR since the last tag. The (#N) suffix on each main commit subject is the PR:

gh pr view N --json number,title,body,author,files,labels

Read the body, and the diff (gh pr diff N) when the body doesn't say what changed for a user. Then write the notes in the style of the last hand-written CHANGELOG entry (CHANGELOG.md, 5.8.0):

## Breaking changes          ← only for a major; what breaks and how to migrate
## Added
- `icu_tool_name` does X for the user. Caveats/limits worth knowing. Contributed by @handle (#N).
## Fixed
- What was wrong, as the user saw it, and what happens now (#N).
## Changed
- ...

This takes the server from A tools to B — `safe` (the default) from C to D, `none` from E to F.

**Full Changelog**: https://github.com/hhopke/intervals-icu-mcp/compare/vPREV...vX.Y.Z

Rules:

  • Describe the release as it ships, not the PR history. Fold follow-up PRs ("apply review feedback", renames, fix-ups of an unreleased feature) into the entry they change, citing all PR numbers, and use the final tool/parameter names: check server.py, not the PR title.
  • Write for a user of the server, naming tools and parameters in backticks and saying what they can now do or what was wrong. Not how the code changed.
  • Leave out what users don't notice: dependency bumps, CI, tests, refactors, OpenAPI spec syncs. Keep ones that change behavior or support (Docker base image, Python versions, a security fix) under Changed or Security.
  • Credit external contributors with "Contributed by @handle" (the PR author.login); not the maintainer (hhopke) and not bots.
  • Tool counts: only when tools were added or removed. Count name="icu_ in server.py and use the per-mode numbers from CLAUDE.md.
  • Omit empty sections. No emojis, no AI attribution.

Write the notes to a file in the scratchpad, show them to the user, and revise until they're happy. Once the run from step 3 has created the draft, upload them:

gh release edit vX.Y.Z --notes-file <path>
gh release view vX.Y.Z --json url,isDraft

5. Hand off

Give the user the draft URL and tell them publishing it tags the commit and publishes to PyPI and the MCP Registry. Stop here unless they explicitly ask you to publish it (see Context).

6. After publishing: watch the release run

gh run watch "$(gh run list --workflow=publish.yml --event=release --limit=1 --json databaseId --jq '.[0].databaseId')" --exit-status

A green run is the success signal: verify only passes once PyPI and the MCP Registry both serve the version and a clean install imports. Don't re-check by hand. mcp-registry can fail after PyPI has published, leaving a partial release (then verify is skipped), so never report success off the pypi job alone. If only verify failed, the uploads went through but the release isn't served or installable yet: report which step failed.

Recovery after publishing: re-run the failed jobs of the same release run (gh run rerun <id> --failed). They reuse the tag, and pypi has skip-existing: true. Don't dispatch again: with no commits past the new tag it reports "Nothing to release". If the cause needs a code change, the tag must move: delete the Release and the tag, fix on main, and dispatch again. Don't retry anything without the user.

Notes can still be corrected after publishing with gh release edit vX.Y.Z --notes-file <path>.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.