release
Skill13 starsChanged 3 months agoApache-2.0View on GitHub
Cuts a Kraft release - a release candidate, a sweep of the installed rc, a fix loop until the sweep is clean, then the stable release on PyPI, GitHub, Homebrew, Open VSX and the VS Code Marketplace. Use when the maintainer asks to cut a release, start with an rc, or ship X.Y.Z.
- Installs packages
193 other projects use a version of this.
Adopted by
Most recently taken up by
- naomiaro/waveform-playlisttheir own version, first seen Nov 16, 2026
- osmlab/name-suggestion-indextheir own version, first seen Nov 16, 2026
- vulnerability-lookup/vulnerability-lookuptheir own version, first seen Nov 16, 2026
- ClickHouse/mcp-clickhousetheir own version, first seen Nov 16, 2026
- bpatrik/pigallery2their own version, first seen Nov 16, 2026
- Shasnow/StarRailAssistanttheir own version, first seen Nov 16, 2026
Used with
Projects with it also use create-agent-adapter, changelog-style and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillcreate-agent-adapter
Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.
Also in 5 projects that use this
GrinvSkillchangelog-style
Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.
Also in 4 projects that use this
Microsoft AzureSkillcomponent-release
Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.
Also in 4 projects that use this
GrinvSkilldocs-consistency-check
Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.
Also in 4 projects that use this
Microsoft AzureSkilldocumentation-consistency
Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.
Also in 8 projects that use this
parcadeiSkillagent-context-isolation
Agent Context Isolation
Also in 3 projects that use this
- +3 more from Grinv
Other versions193 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 193
- paperclipai/paperclip★ 114ksame name
- modelcontextprotocol/servers★ 92ksame name
- remotion-dev/remotion★ 73ksame name
- traefik/traefik★ 66ksame name
- usememos/memos★ 64ksame name
- tw93/Pake★ 64ksame name
- AmruthPillai/Reactive-Resume★ 46ksame name
- amruthpillai/reactive-resume★ 46ksame name
- reactive-resume/reactive-resume★ 46ksame name
- Yeachan-Heo/oh-my-claudecode★ 41ksame name
183 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 4 are distinctive, and 12 are very specific to this project.
0
Common
Most of the 183 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Run the scripts from the repo root: .claude/skills/release/scripts/….
- Very specific: line 53
Every run, dry or real, goes the same way.
- Very specific: line 64
Read its job log (gh run view <id> --log).
- Very specific: line 79
Read RELEASING.md and the top of release.yml.
- Very specific: line 84
Check open PRs for anything that looks meant for this release, and mention it (gh pr list).
- Distinctive: line 89
Wait for it if it's still running.
- Very specific: line 93
Do not rerun the tests locally.
- Very specific: line 107
If it concluded success, wait in the background: .claude/skills/release/scripts/wait_published.sh X.Y.ZrcN.
- Very specific: line 115
Test what users will install: the wheel from PyPI, in a clean venv on Python 3.12 (the floor), with its own KRAFT_HOME and port.
- Distinctive: line 139
Delete the work dir when you're done with it.
- Distinctive: line 163
Prove it: before pushing: the checks steward lists for the paths you touched, and the step that failed again.
- Very specific: line 178
Highlight: if the rc notes had no Highlights section, propose the headline PR.
- Very specific: line 183
If they picked a highlight, add the label: gh pr edit <n> --add-label notes::highlight.
- Very specific: line 196
If the script exits 1 (a target still not serving after 30 minutes) on a run that concluded success, report it and confirm by hand with the …
- Distinctive: line 212
Stop and report: the run, the step that failed, and its log.
- Very specific: line 227
If it's still open, watch it to green.
“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Release Kraft
This drives the release workflow (.github/workflows/release.yml) on
itsOmidKarami/kraft, checks every output, and stops only for the maintainer's
decisions. RELEASING.md and release.yml are the source of truth: read both at
the start of every run, and where they disagree with this skill, they win.
Two names, used throughout:
<last-tag>: the newest exactvX.Y.Ztag, the one this release follows.X.Y.Z: the version being released. The workflow computes it from the largestrelease::label among the PRs since<last-tag>; read it from the dry run. Never pick a number yourself.
Run the scripts from the repo root: .claude/skills/release/scripts/….
Never hand-edit CHANGELOG.md, vscode/CHANGELOG.md, plugin manifest
versions, or _Added in next_ notes. The release writes them.
Stop and ask the maintainer before:
- Changing a label on any PR but your own fix PRs (for example adding
notes::highlight). - The stable (non-rc) run. PyPI publishes cannot be undone.
- Any fix that changes code, unless they have already said "fix what you find".
- Anything after a real run that did not conclude
success: no rerun, no publishing by hand, no yanking. - Treating a Phase 3 finding as not blocking the release: report it with your view and wait for their ruling.
An rc run needs no extra confirmation once they have asked for one, unless its dry run plans a version they would not expect (a major, or a number other than the one the last rc led to).
Tools. The steps use gh. When gh auth status fails (a cloud session has
gh but no valid token), use the GitHub MCP tools instead:
references/github-mcp.md gives each step's MCP form and its gotchas.
preflight -> rc dry run -> rc -> rc sweep --clean--> ask -> stable dry run -> go? -> stable -> stamp PR
^ |finding
+------ fix on main, next rc ---+Dispatching a run
Every run, dry or real, goes the same way. gh workflow run returns before the
run exists, so the newest run straight after a dispatch is often the previous one.
- Note the newest
release.ymlrun's id:gh run list --workflow release.yml -L 1 --json databaseId. - Dispatch, always with
sha, so the release is the commit that passed CI even if someone merges in the meantime:gh workflow run release.yml --ref main -f dry_run=<true|false> -f pre=<rc|none> -f sha=<sha>. - Poll until a
workflow_dispatchrun with a larger id appears, created after your dispatch by your account (another dispatch in the same minute would otherwise pass for yours), then wait until it'scompleted(gh run watch <id>in the background). - Read its job log (
gh run view <id> --log). It prints the notes (Highlights if any, New, Fixes, each line ending in its PR number), then one of:dry run: would release vX.Y.Z…: a dry run's plan.releasing vX.Y.Z…: a real run. A real run whose log lacks this line is the wrong run.nothing since <last-tag> ships; not releasing: every PR isrelease::none. Stop and report.- an error naming a PR: a label problem (no
release::label or two, a misspellednotes::label,notes::highlighton arelease::nonePR). Report it; fixing someone's label is the maintainer's call.
Phase 1: Preflight
Is there something to release, and is main's tip safe to release from?
- Read
RELEASING.mdand the top ofrelease.yml. git fetch origin main --tags, then find<last-tag>the way the workflow does:git tag --list | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1.- List what ships:
git log --first-parent --oneline <last-tag>..origin/main. Each squash commit ends in its PR number. Note the likely headline. - Check open PRs for anything that looks meant for this release, and mention it
(
gh pr list). - Main's tip must have a
testrun on a push that iscompleted/success, or the workflow refuses it:gh run list --workflow test --branch main --event push --commit <sha>. Wait for it if it's still running.
Record the tip sha. Every later run is pinned to it.
Do not rerun the tests locally. That test run covers lint, the docs checks,
intent pins, the backend suite, the frontend and the demo smoke, and the workflow
will not release a sha without it. What CI cannot see is the published wheel,
which Phase 3 installs.
Phase 2: Cut the release candidate
An rc goes to PyPI and a GitHub pre-release, and nothing else: no Homebrew, no stamp PR, no Marketplace, no Open VSX.
- Dry run with
pre=rc(see "Dispatching a run"). Show the maintainer the notes and the plannedvX.Y.ZrcN, then go on: stop only for a version they wouldn't expect (above). - Real run, the same inputs with
dry_run=false. - If it concluded
success, wait in the background:.claude/skills/release/scripts/wait_published.sh X.Y.ZrcN. Then check the GitHub Release (gh release view vX.Y.ZrcN): a pre-release, the install line at the top of its notes, the wheel andkraft-X.Y.ZrcN.vsixattached. If it did not concludesuccess, see "A real run that failed".
Phase 3: Sweep the release candidate
Test what users will install: the wheel from PyPI, in a clean venv on Python
3.12 (the floor), with its own KRAFT_HOME and port.
.claude/skills/release/scripts/smoke.sh X.Y.ZrcN(a second argument picks the port, default 8799). It prints:- the version, which must be the rc
kraft admin health:status okand the rc versionkraft admin doctor: every checkok, except the expected failures belowkraft admin templates lint: no errors- the web UI's
<title>Kraft
- Exercise the headline feature by hand on the installed rc. smoke.sh
proves the wheel installs and starts, not that the release's features work,
so this step and the next are required. The script stopped its server; run
every command through
scripts/kraft.sh <work dir> <port> …, which gives it the same isolation in any shell:
Feed it inputs that should pass and one that should fail, and check that the CLI tells them apart. For a chain feature, say: a chain that lints clean and one thatS=.claude/skills/release/scripts/kraft.sh; W=<the work dir it printed>; P=8799 $S $W $P admin start --port $P > $W/server2.log 2>&1 & # $S $W $P admin stop when doneadmin templates lintmust name. - Pick one or two more features from the notes that a smoke run can reach, and exercise them the same way.
- Delete the work dir when you're done with it.
Expected doctor results (not regressions): kraft on PATH always fails,
since the smoke venv is never on PATH; mcp server fails or warns where
Kraft's MCP isn't registered in Claude Code's settings (it reads only the
registration, so it can pass while the MCP server is down). Anything else
failing or warning is a finding.
The sweep is clean when smoke.sh shows everything listed in step 1, and steps 2 and 3 turned up nothing the maintainer rules blocking.
Fix loop
A finding from Phase 3 is fixed on main and shipped as the next rc; an rc is never patched in place.
- Report the finding: what failed, the command, the output, and whether it blocks the release. One the maintainer rules non-blocking is noted for the final report and doesn't hold up Phase 4.
- Fix it on a branch, following
CONTRIBUTING.mdand/steward: one PR per fix, with a## Changelogsection and arelease::label you choose and tell the maintainer about. A fix to a feature no stable release has shipped yet isrelease::none, since the feature's own entry covers it. A fix to something users already have isrelease::patch. - Prove it before pushing: the checks steward lists for the paths you touched, and the step that failed again.
- Open the PR, watch it to green, and ask the maintainer to merge it (or merge it if they have said to).
- Back to Phase 1 on the new tip, then the next rc. The workflow numbers it
rcN+1itself.
Repeat until a full Phase 3 sweep comes back clean (see its last line). Only then go on to Phase 4.
Phase 4: Stable release
The stable run publishes everywhere and cannot be undone.
- Ask in one prompt (
AskUserQuestion, with a recommended option):- Highlight: if the rc notes had no Highlights section, propose the
headline PR. Check first that its
## Changelogline reads as a headline. - Credentials: you cannot check them. Ask the maintainer to confirm the two
under "Before a stable run" in
RELEASING.md. If the Marketplace identity or its federated credential is gone, the publish fails and the run goes red.
- Highlight: if the rc notes had no Highlights section, propose the
headline PR. Check first that its
- If they picked a highlight, add the label:
gh pr edit <n> --add-label notes::highlight. git fetch origin main. For each PR number ingit log --first-parent --oneline <sha>..origin/main, read its labels withgh pr view <n> --json labels. Any that isn'trelease::noneisn't in the rc you swept: go back to Phase 1 for a new rc, or ask the maintainer whether to release the pinned sha anyway.- Dry run with
pre=noneand the samesha. The version must be the last rc's without its suffix (v2.3.0afterv2.3.0rc2). If it is not, a label changed since the rc: stop and report. - Ask Go / hold, showing the notes and the version.
- On Go, the real run, the same inputs with
dry_run=false. If it concluded
success, wait in the background:.claude/skills/release/scripts/wait_published.sh X.Y.Z pypi brew openvsx. If the script exits 1 (a target still not serving after 30 minutes) on a run that concludedsuccess, report it and confirm by hand with the per-target check under "What a stable run publishes" inRELEASING.md: after asuccessrun it is more likely lag than a missed publish. Then check the rest:Target Check GitHub Release vX.Y.Z, not a pre-release, wheel and.vsixattachedVS Code Marketplace the run's "publish the VS Code extension" step succeeded, and its "check the Marketplace lists this release" step ended without its 5-minute warning; if it warned, npx --prefix vscode vsce show kraft-sdlc.kraftnames the version. A failed publish step usually means the identity's login or membership lapsed, and the extension is not published: report it.Docs the docsrun the release dispatched passed; a warning that it was not dispatched means rundocsby hand.claude/skills/release/scripts/smoke.sh X.Y.Z, as in Phase 3.
A real run that failed
Stop and report: the run, the step that failed, and its log. Do not rerun,
publish by hand, or yank anything without the maintainer. What happens next
depends on where it failed. A build before the tag push leaves nothing behind,
and a rerun, once they agree, is safe. After the tag, a rerun plans nothing, and the targets that
did not publish are finished by hand. RELEASING.md, "What a stable run
publishes", lists the steps in order and the commands for each.
Phase 5: After the release
The release is done when the stamp PR has merged.
- Stamp PR. The release bot opens
chore: stamp plugin manifests and changelog for vX.Y.Z(release::none) and auto-merges it once CI passes. Find it withgh pr list --state all --search "stamp plugin manifests vX.Y.Z". If it's still open, watch it to green. If a check fails, read that check's log and report it. A patch release that ships an_Added in next_note does not fail it: the stamp step warns and adds a line to the PR (RELEASING.md, "Docs Added in notes"). - What's new. Open a
release::nonepull request that adds the release's section todocsite/content/6.project/3.whats-new.md, newest first: itsnotes::highlightentries (one with sub-bullets counts as one) and at most two more of its most notable changes, a bullet each with a link to the page that describes it, under<!-- not new: shipped in X.Y -->. A patch release adds nothing. - Report, outcome first: the version, where it is published, what the rc and stable smoke runs checked, anything that warned, and the release link.
- Offer an announcement. Build it from
CHANGELOG.mdon main, grouped by theme rather than by version, with the install lines (uv tool install kraft-sdlc,brew tap itsOmidKarami/kraft && brew install kraft,kraft admin update) and the live demo, https://kraft-sdlc.dev/demo/. Keep every feature claim to what the changelog says.
Gotchas
| Gotcha | What to do |
Foreground sleep is blocked | Wait with a run_in_background command or a Monitor. Never chain short sleeps. |
git pull origin main on a cloud session's branch | It fast-forwards the branch, and the stop hook reports an unpushed commit. Use git fetch only; if it happens, push the branch, which carries only main's commits. |
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.

