Menu
Create a new ATK release. Handles pre-flight checks, changelog generation, tagging, pushing, CI verification, and PyPI publication confirmation. Use when asked to cut a release, publish a new version, or ship changes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | release |
| description | Create a new ATK release. Handles pre-flight checks, changelog generation, tagging, pushing, CI verification, and PyPI publication confirmation. Use when asked to cut a release, publish a new version, or ship changes. |
| argument-hint | [version, e.g. 0.3.0] |
You are performing a release of the atk-cli package. This is a critical operation — follow every step in order. Do not skip steps. Do not assume success — verify it.
ATK uses hatch-vcs: the version is derived from git tags at build time, not hardcoded.
vX.Y.Z (e.g., v0.2.1)Z): bug fixes, small features, non-breaking changesY): new user-facing features, new commands, behavioral changesX): breaking changes to CLI interface, manifest schema, or plugin APIv1.0.0: minor bumps are for significant milestones; patches are the normPyPI receives the version without the v prefix (e.g., 0.2.1).
CRITICAL: PyPI does not allow re-uploads. If a version is published, it is permanent. Never force-move a tag that has been pushed. If a mistake is published, bump to the next patch.
If version was provided as argument, use v$ARGUMENTS. Otherwise:
git tag --sort=-v:refname | head -1 to find the current latest taggit log <latest-tag>..HEAD --oneline to see what changedRun ALL of these checks. If ANY fail, stop and report.
git status --short
EXPECT: Empty output (no uncommitted changes). If dirty, stop — all changes must be committed before release.
git branch --show-current
EXPECT: main. Releases are only cut from main.
git fetch origin main
git rev-list HEAD..origin/main --count
EXPECT: 0 (no commits on origin/main that we don't have). If behind, stop — pull first.
make check
EXPECT: Exit 0. This runs ruff (lint), mypy (types), and pytest (tests). All must be green.
gh run list --branch main --limit 3
EXPECT: The most recent CI run for HEAD is completed / success. If CI hasn't run for the current HEAD yet, wait or trigger it.
Check if there are any issues/PRs that should block this release:
gh issue list --state open --label "blocker" --limit 5
If blockers exist, report them and ask Sasha whether to proceed.
Generate a thorough changelog by analyzing what changed since the last release.
git tag --sort=-v:refname | head -1
git log <last-tag>..HEAD --oneline --no-merges
git diff <last-tag>..HEAD --stat
Read each commit and the diff. Organize into categories:
Write release notes in this format:
## What's New
### <Feature Name>
<2-3 sentence description with usage example>
### <Feature Name>
...
## Bug Fixes
- <one-liner per fix>
## Breaking Changes
- <one-liner with migration guidance>
## Upgrade
\```bash
pip install --upgrade atk-cli
# or
uv tool upgrade atk-cli
\```
<Any migration notes if needed>
Present the draft to Sasha for review before proceeding.
Before tagging, manually verify the key changes work. This is NOT optional.
For each new feature or significant change:
At minimum, always test:
atk --version outputs a valid versionatk status works without errors (if ATK Home exists)Only proceed here if all previous steps passed and Sasha approved the release notes.
git tag v<VERSION>
git push origin main
git push origin v<VERSION>
The tag push triggers the Publish to PyPI workflow automatically.
Both workflows must succeed before the release is complete.
gh run list --branch main --limit 3
Wait until the CI run for the current commit shows completed / success.
gh run list --workflow publish.yml --limit 3
Wait until the publish run shows completed / success.
If either workflow fails:
gh run view <run-id> --log | tail -50curl -s https://pypi.org/pypi/atk-cli/<VERSION>/json before deciding next steps.curl -s https://pypi.org/pypi/atk-cli/<VERSION>/json | python3 -c "import sys,json; d=json.load(sys.stdin); print('Version:', d['info']['version']); print('Summary:', d['info']['summary'])"
EXPECT: Version matches the release version. If this fails, the publish did not actually land on PyPI — investigate before creating the GitHub release.
gh release create v<VERSION> --title "v<VERSION> — <Short Title>" --notes "<release notes from Step 2>"
Use a HEREDOC for multi-line notes:
gh release create v<VERSION> --title "v<VERSION> — <Title>" --notes "$(cat <<'EOF'
<release notes here>
EOF
)"
gh release view v<VERSION>
uv pip install atk-cli==<VERSION> --dry-run
Summarize to Sasha:
https://pypi.org/project/atk-cli/<VERSION>/https://github.com/Svtoo/atk/releases/tag/v<VERSION>| Failure | Recovery |
|---|---|
| CI fails after tag push | Fix the issue, push fix to main, bump to next patch, re-tag |
| Publish fails but PyPI has the version | The version is burned — create GitHub release as-is |
| Publish fails and PyPI does NOT have it | Fix issue, delete the tag (git tag -d v<X> && git push origin :refs/tags/v<X>), re-tag same commit |
| Wrong content released | Cannot re-upload to PyPI. Bump patch, fix, release again |
| Tag pushed to wrong commit | If not yet on PyPI: delete remote tag, re-tag correct commit. If on PyPI: bump patch |