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
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-toolSkill
- commitSkill
- release-checkSkill
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
- Very specific: line 37
Publishing is the maintainer's call: Never publish the draft without the user's explicit go-ahead for that specific release.
- Very specific: line 47
No draft release is pending: gh release list --limit 5 (a leftover draft makes the dispatch fail in draft-release.
- Very specific: line 65
If next_version.py says there is nothing to release, stop.
- Distinctive: line 69
Wait for the user's explicit go-ahead with the final version.
- Distinctive: line 76
Start the watch in the background and write the notes (step 4) while the tests run:
- Very specific: line 82
If it fails, surface gh run view <id> --log-failed and stop.
- Very specific: line 93
Read the body, and the diff (gh pr diff N) when the body doesn't say what changed for a user.
- Very specific: line 122
Tool counts: only when tools were added or removed.
- Distinctive: line 126
Write the notes to a file in the scratchpad, show them to the user, and revise until they're happy.
- Distinctive: line 153
Don't dispatch again: with no commits past the new tag it reports "Nothing to release".
≈ “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.
Files
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):
| Job | Does |
preflight | Fails 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") |
test | Full test suite (reusable test.yml) |
draft-release | Refuses 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):
| Job | Does |
pypi | Builds at the new tag and publishes to PyPI |
mcp-registry | Syncs server.json to the tag version and publishes to the MCP Registry |
verify | Polls 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 withorigin/main, tags fetched (git fetch origin main --tags). make can-releaseis green (or run/release-check).- No draft release is pending:
gh release list --limit 5(a leftover draft makes the dispatch fail indraft-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]*')"..HEADShow 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 beenfeat, 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 overrideStart 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-statusIf 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,labelsRead 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.ZRules:
- 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_inserver.pyand 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,isDraft5. 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-statusA 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>.
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
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.

