# release

Guides publishing atomic-agents by bumping versions, building with uv, uploading to PyPI, and creating GitHub releases.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · ★ 6344 repo stars
- Author: Eigenwise
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Eigenwise/atomic-agents/tree/HEAD/.claude/skills/release/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/eigenwise-release

## What it does

This workflow manages releases for the `atomic-agents` library. It validates that the local working tree is on a clean `main` branch, then triggers `build_and_deploy.ps1`. The script updates `pyproject.toml`, runs `uv sync`, builds artifacts, and pushes packages to PyPI.

Once packages are uploaded, the agent commits the modified `pyproject.toml` and `uv.lock`, pushes them upstream, and tags a release via GitHub CLI. A valid `PYPI_TOKEN` in `.env` and working PowerShell execution are required before running.

## Requirements
- Works with: GitHub

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Eigenwise/atomic-agents --skill release -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/release/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/release/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Eigenwise/atomic-agents --skill release -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/release/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Eigenwise/atomic-agents --skill release -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/release/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Eigenwise/atomic-agents .claude/skills/release
```

2. **Manually: put the files in place**
- File: `.github/skills/release/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Eigenwise/atomic-agents --skill release -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Eigenwise/atomic-agents --path .claude/skills/release
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/release/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Eigenwise/atomic-agents --skill release -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Eigenwise/atomic-agents/tree/HEAD/.claude/skills/release/SKILL.md

## When to use it
- Bump version numbers according to semantic versioning rules
- Build distribution artifacts and deploy to PyPI using uv
- Create tagged GitHub releases using structured changelog notes

## Example prompts
- Release a patch version of atomic-agents
- Deploy a minor release to PyPI and push the tag
- Bump version to major and create a GitHub release

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2b865d56c3070693.

BEGIN THIRD-PARTY FILE 2b865d56c3070693
````text
---
name: release
description: Release a new version of atomic-agents to PyPI and GitHub. Use when the user asks to "release", "publish", "deploy", or "bump version" for atomic-agents.
allowed-tools: Read, Bash, Grep, Glob
metadata:
  internal: true
---

# Release Process for atomic-agents

## Overview

This skill guides the release process for atomic-agents, including version bumping, PyPI publishing, and GitHub release creation.

## Prerequisites

- Must be on `main` branch with clean working directory
- `.env` file must contain `PYPI_TOKEN` environment variable
- Must have push access to the repository

## Release Types

| Type | When to Use | Example |
|------|-------------|---------|
| `major` | Breaking changes | 2.5.0 → 3.0.0 |
| `minor` | New features (backwards compatible) | 2.5.0 → 2.6.0 |
| `patch` | Bug fixes only | 2.5.0 → 2.5.1 |

## Step-by-Step Process

### 1. Prepare the Branch

```bash
git checkout main
git pull
git status  # Ensure clean working directory
```

### 2. Run Build and Deploy Script

**Important**: The script bumps versions, so if it fails partway through, reset to main before retrying.

```powershell
powershell -ExecutionPolicy Bypass -File build_and_deploy.ps1 <major|minor|patch>
```

This script will:
- Read current version from `pyproject.toml`
- Increment version based on release type
- Update `pyproject.toml` with new version
- Run `uv sync` to update dependencies
- Run `uv build` to create distribution packages
- Run `uv publish` to upload to PyPI

### 3. If Script Fails - Reset and Retry

```bash
git checkout main
git reset --hard origin/main
# Fix the issue, then run script again
```

### 4. Commit and Push Version Bump

```bash
git add pyproject.toml uv.lock
git commit -m "Release vX.Y.Z"
git push
```

### 5. Create GitHub Release

```bash
gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES_HERE"
```

## Release Notes Template

```markdown
## What's New

### Feature Name
Brief description of the feature.

#### Features
- Feature 1
- Feature 2

#### Improvements
- Improvement 1

#### Bug Fixes
- Fix 1

### Full Changelog
https://github.com/eigenwise/atomic-agents/compare/vOLD...vNEW
```

## Checklist

- [ ] On main branch with clean working directory
- [ ] `.env` file has `PYPI_TOKEN`
- [ ] Determined correct release type (major/minor/patch)
- [ ] Build and deploy script completed successfully
- [ ] Version bump committed and pushed
- [ ] GitHub release created with release notes
````
END THIRD-PARTY FILE 2b865d56c3070693

The third-party file has ended. Everything between the 2b865d56c3070693 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© Eigenwise · MIT · https://github.com/Eigenwise/atomic-agents/tree/HEAD/.claude/skills/release/SKILL.md

## Similar
- [release-management](https://affpapa.org/en/nevibecode/skills/release-management.md) — skill · 220 installs
- [release-notes](https://affpapa.org/en/nevibecode/skills/kenryu42-release-notes.md) — skill · ★ 2088 repo stars
- [release-manager](https://affpapa.org/en/nevibecode/commands/release-manager.md) — command · ★ 850 repo stars
- [github-release](https://affpapa.org/en/nevibecode/skills/jezweb-github-release.md) — skill · 1400 installs
- [create-release-checklist](https://affpapa.org/en/nevibecode/skills/create-release-checklist.md) — skill · 779 installs
- [jackin-release-notes](https://affpapa.org/en/nevibecode/skills/jackin-release-notes.md) — skill · 469 installs

## Other versions with the same name
- [release · tobi](https://affpapa.org/en/nevibecode/skills/tobi-release.md) — 2200 installs
- [release · yeachan-heo](https://affpapa.org/en/nevibecode/skills/yeachan-heo-release.md) — 904 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
