release skill
Automates the complete pre-release workflow for Python packages using uv and ruff, including version calculation and changelog updates.
- GitHub stars
- 45
- Files
- 1
- Last commit
- May 31, 2026
- License
- MIT
- Allowed tools
- 6
What does the release skill do?
release automates the complete pre-release workflow for Python packages using uv and ruff, including version calculation and changelog updates.
Summary generated from the skill's SKILL.md.
About the release skill
Automating the pre-release workflow for Python packages is what this skill enables for developers using uv and ruff. It manages a strict nine-step sequence that begins with verifying the git branch and working directory status before pulling the latest changes from main. The process ensures code quality by running pytest for testing and ruff for both linting and formatting checks.
Once verification passes, the tool builds the package with uv and offers to trigger a changelog-agent to update the CHANGELOG.md file based on recent commits. It calculates the next semantic version by analyzing change types like added, fixed, or removed entries within the unreleased section of the changelog. After the user confirms the version, the skill updates the changelog, commits the changes, and creates an annotated git tag to finalize the release process.
What an agent can do with it
- 1Automate Python package releasesExecute a complete pre-release workflow for Python packages using uv and ruff.
- 2Calculate semantic versions from changelogsDetermine the next version number by analyzing the types of changes in the unreleased section.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the release skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the release skill in Plugin
/plugin marketplace add sequenzia/agent-alchemy /plugin install agent-alchemy-dev-tools@agent-alchemy
Install the release skill in Claude Code
~/.claude/skills/release/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/dev-tools/skills/release-python-package ~/.claude/skills/releaseInstall the release skill in Claude Code (project)
.claude/skills/release/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/dev-tools/skills/release-python-package .claude/skills/releaseInstall the release skill in Codex
~/.agents/skills/release/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/dev-tools/skills/release-python-package ~/.agents/skills/releaseInstall the release skill in Gemini CLI
~/.gemini/skills/release/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/dev-tools/skills/release-python-package ~/.gemini/skills/releaseInstall the release skill in Claude.ai
npx degit sequenzia/agent-alchemy/claude/dev-tools/skills/release-python-package release && zip -r release.zip release # claude.ai → Customize → Skills → + → Create skill → Upload a skill → release.zip
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesequenzia/agent-alchemy/claude/dev-tools/skills/release-python-package is public and reachablegithub.com/sequenzia/agent-alchemy/tree/HEAD/claude/dev-tool ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-05-31github.com/sequenzia/agent-alchemy/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/sequenzia/agent-alchemy/blob/HEAD/claude/dev-tool ↗Pass
- Pre-approved tools are scopedBash lets the agent run any shell command without askinggithub.com/sequenzia/agent-alchemy/blob/HEAD/claude/dev-tool ↗Finding
- SKILL.md follows the Agent Skills formatname "release" differs from the folder "release-python-package"github.com/sequenzia/agent-alchemy/blob/HEAD/claude/dev-tool ↗Finding
SKILL.md
View on GitHubPython Release Manager
Execute a complete pre-release workflow for Python packages using uv and ruff. This command automates version calculation, changelog updates, and tag creation.
Arguments
$ARGUMENTS- Optional version override (e.g.,1.0.0). If not provided, version is calculated from changelog entries.
Workflow
Execute these 9 steps in order. Fail fast: Stop immediately if any verification step fails.
Step 1: Pre-flight Checks
Run these checks and stop if any fail:
# Check current branch
git branch --show-current
- Must be on
mainbranch. If not, stop and report: "Release must be run from the main branch. Currently on: {branch}"
# Check for uncommitted changes
git status --porcelain
- Must have clean working directory. If output is not empty, stop and report: "Working directory has uncommitted changes. Please commit or stash them first."
# Pull latest changes
git pull origin main
- Report any merge conflicts and stop if they occur.
Step 2: Run Tests
Execute the test suite:
uv run pytest
- If tests fail, stop and report the failure output
- If tests pass, report: "All tests passed"
Step 3: Run Linting
Execute linting checks:
uv run ruff check
uv run ruff format --check
- If either command fails, stop and report the issues
- If both pass, report: "Linting and formatting checks passed"
Step 4: Verify Build
Build the package:
uv build
- If build fails, stop and report the error
- If build succeeds, report: "Package builds successfully"
Step 5: Changelog Update Check
All verification checks have passed. Before calculating the version, offer to run the changelog-agent to ensure the [Unreleased] section is up-to-date.
Use AskUserQuestion:
Would you like to run the changelog-agent to update CHANGELOG.md before proceeding?
This will analyze git commits since the last release and suggest new changelog entries.
Options:
- "Yes, update changelog first (Recommended)" - Recommended option
- "No, continue with existing changelog"
If user selects "Yes":
Use the Task tool to spawn the changelog-agent:
- subagent_type:
changelog-manager - prompt: "Analyze commits since the last release and update the CHANGELOG.md [Unreleased] section"
- The agent will analyze commits, suggest entries, and update CHANGELOG.md after user approval
- Wait for the agent to complete before proceeding
If user selects "No":
Continue to Step 6 (Calculate Version) without running the changelog-agent.
Step 6: Calculate Version
6.1 Read CHANGELOG.md
Read CHANGELOG.md and parse its structure. Look for:
- The
## [Unreleased]section and its subsections - The most recent versioned section (e.g.,
## [0.1.0]) to get the current version
6.2 Analyze Change Types
Count entries under [Unreleased] by subsection:
### Added- New features### Changed- Changes to existing functionality### Deprecated- Features marked for removal### Removed- Removed features (breaking change)### Fixed- Bug fixes### Security- Security fixes
6.3 Calculate Suggested Version
Apply semantic versioning rules to the current version (MAJOR.MINOR.PATCH):
| Condition | Bump Type | Example |
|---|---|---|
### Removed present AND current >= 1.0.0 |
MAJOR | 1.2.3 → 2.0.0 |
### Removed present AND current < 1.0.0 |
MINOR | 0.2.3 → 0.3.0 |
### Added or ### Changed present |
MINOR | 0.1.0 → 0.2.0 |
Only ### Fixed, ### Security, or ### Deprecated |
PATCH | 0.1.0 → 0.1.1 |
6.4 Handle Edge Cases
- No unreleased changes: Warn user "No entries found under [Unreleased]. Are you sure you want to release?"
- Missing CHANGELOG.md: Stop and report "CHANGELOG.md not found. Please create one following Keep a Changelog format."
- Version override provided: Use
$ARGUMENTSas the version instead of calculating
6.5 User Confirmation
Use AskUserQuestion to confirm the version:
Based on changelog analysis:
- Found: {count} Added, {count} Changed, {count} Fixed, {count} Removed entries
- Current version: {current}
- Suggested version: {suggested} ({bump_type} bump)
Confirm version or provide override:
Options:
- "Confirm {suggested}"
- "Enter different version"
Step 7: Update CHANGELOG.md
7.1 Get Repository URL
Read pyproject.toml and extract the repository URL from [project.urls]:
- Check keys:
Repository,repository,Source,source,Homepage,homepage - Extract the GitHub/GitLab URL
If no repository URL found, warn but continue (comparison links will be omitted).
7.2 Update Changelog Content
Transform the changelog:
Before:
## [Unreleased]
### Added
- New feature X
## [0.1.0] - 2024-01-15
### Added
- Initial release
[Unreleased]: https://github.com/user/repo/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/user/repo/releases/tag/v0.1.0
After (releasing 0.2.0):
## [Unreleased]
## [0.2.0] - {today's date YYYY-MM-DD}
### Added
- New feature X
## [0.1.0] - 2024-01-15
### Added
- Initial release
[Unreleased]: https://github.com/user/repo/compare/v0.2.0...HEAD
[0.2.0]: https://github.com/user/repo/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/user/repo/releases/tag/v0.1.0
7.3 Write Updated CHANGELOG.md
Use the Edit tool to update CHANGELOG.md with the transformed content.
Step 8: Commit Changelog
Stage and commit the changelog update:
git add CHANGELOG.md
git commit -m "docs: update changelog for v{version}"
git push origin main
Report: "Changelog committed and pushed"
Step 9: Create and Push Tag
Create an annotated tag and push it:
git tag -a v{version} -m "Release v{version}"
git push origin v{version}
Final Report
Report success with details:
Release v{version} completed successfully!
- Changelog updated: CHANGELOG.md
- Tag created: v{version}
- Tag URL: {repository_url}/releases/tag/v{version}
Next steps:
- GitHub/GitLab will create a release from the tag
- Publish to PyPI if configured in CI
Error Recovery
If any step fails after Step 6 (version confirmation):
- Report which step failed and the error
- Provide commands to manually complete or rollback:
git checkout CHANGELOG.md- Revert changelog changesgit tag -d v{version}- Delete local tag if createdgit push origin :refs/tags/v{version}- Delete remote tag if pushed
Files in this skill
1release skill questions
How do I install the release skill in Claude Code?
Run npx degit sequenzia/agent-alchemy/claude/dev-tools/skills/release-python-package ~/.claude/skills/release. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the release skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What tools are required for this release workflow?
The workflow uses uv for package management and testing, and ruff for linting and formatting.
Can I manually specify a version for the release?
Yes, you can provide an optional version override as an argument (e.g., 1.0.0).