# Release

> Manages package release workflows for npm and Swift/macOS ecosystems (Python and Go coming soon). Detects project type from manifest files, bumps versions, transforms changelogs (Keep a Changelog format), creates git commits and tags, and optionally generates CI publishing workflows or GitHub Releases. Use when releasing packages, cutting versions, publishing to registries, bumping versions, setting up release infrastructure, checking release readiness, doing a dry run before publishing, creating pre-release versions, or tagging a new release.

- Skill: `neethanwu/release` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add neethanwu/release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neethanwu/release/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: neethanwu (https://skillmd.com/u/neethanwu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neethanwu/release

---


# Release

One command to release any package. Detects your ecosystem, bumps the version,
updates the changelog, commits, tags, pushes, and watches CI.

## Commands

| Command | What it does |
|---------|-------------|
| `/release patch` | Bump patch version and release |
| `/release minor` | Bump minor version and release |
| `/release major` | Bump major version and release |
| `/release alpha` | Create alpha pre-release |
| `/release beta` | Create beta pre-release |
| `/release rc` | Create release candidate |
| `/release context` | Show version, commits, changelog status (read-only) |
| `/release dry` | Simulate a release without mutations |
| `/release setup-ci` | Generate CI/CD workflow files |

---

## Step 1: Parse Arguments

Determine the release type from the invocation:

- `patch`, `minor`, `major` → stable release
- `alpha`, `beta`, `rc` → pre-release
- `context` → read-only status
- `dry` → dry run simulation
- `setup-ci` → CI workflow generation
- No argument → show this command reference and stop

---

## Step 2: Detect Ecosystem

Scan the project root for manifest files to determine the ecosystem:

| File present | Ecosystem | Next step |
|-------------|-----------|-----------|
| `package.json` with a `version` field | **npm** | Read [adapters/npm.md](adapters/npm.md) |
| `Package.swift` with `.executableTarget` | **Swift** | Read [adapters/swift.md](adapters/swift.md) |
| `pyproject.toml` | **Python** | Not yet supported — print message and stop |
| `go.mod` | **Go** | Not yet supported — print message and stop |
| None of the above | **Unknown** | Print: "Unsupported project type. This skill supports: npm and Swift/macOS (now), Python and Go (coming soon)." and stop |

To check for `.executableTarget`: `grep -q '\.executableTarget' Package.swift`

For the **npm** ecosystem, also detect the package manager:

| Lock file present | Package manager |
|-------------------|----------------|
| `bun.lock` or `bun.lockb` | bun |
| `pnpm-lock.yaml` | pnpm |
| `yarn.lock` | yarn |
| `package-lock.json` | npm |
| None of the above | npm (default) |

If multiple lock files exist, use the highest match from the table (top = highest priority) and note the conflict to the user.

### Guard Rails

Before proceeding, check for known unsupported configurations:

1. Read `package.json` and check for a `workspaces` field. If present:
   - Print: "Monorepo detected (`workspaces` field found). This skill supports single-package repos only. For monorepos, see changesets or release-please."
   - Stop.

2. Check for `"private": true` in `package.json`. If present:
   - Print: "Note: Package is marked `private`. Publishing will be skipped, but version bumping, changelog management, and tagging will still work."
   - Continue (do not stop).

---

## Step 3: Check Infrastructure

Check for CHANGELOG.md with an `## [Unreleased]` section (case-insensitive),
a pre-push hook at `.git/hooks/pre-push` containing release validation, and
CI publish workflows in `.github/workflows/`.

For `context`: report what's missing — don't offer to create anything.

For all other commands: if CHANGELOG.md is missing or has no `[Unreleased]`
section, route to [flows/init.md](flows/init.md) first. After init, note
missing infrastructure (hook, CI) to offer post-release.

---

## Step 4: Route to Flow

Read the adapter file identified in Step 2, then follow the appropriate flow:

| Command | Flow |
|---------|------|
| `patch`, `minor`, `major` | [flows/release.md](flows/release.md) — 10-step release flow |
| `alpha`, `beta`, `rc` | [flows/pre-release.md](flows/pre-release.md) — pre-release flow |
| `context` | [flows/context.md](flows/context.md) — read-only status report |
| `dry` | [flows/dry-run.md](flows/dry-run.md) — simulation without mutations |
| `setup-ci` | [flows/setup-ci.md](flows/setup-ci.md) — CI workflow generation |

---

## Step 5: Post-Release Offers

After a successful stable release (push completed), check and offer:

1. **Pre-push hook not installed?** → "Would you like to install a pre-push hook to validate releases? It checks that tag versions match your manifest and changelog."

2. **No CI publish workflow?** → Check if the remote contains `github.com`. If yes: "Would you like to generate GitHub Actions workflows for CI and automated publishing? Run `/release setup-ci`." If not on GitHub: "No CI publish workflow detected. `/release setup-ci` can generate GitHub Actions workflows if needed, but note that only GitHub Actions is supported at this time."

These are suggestions only — never install automatically without confirmation.

---

## Rollback

If anything goes wrong during a release, see [reference/rollback.md](reference/rollback.md) for exact recovery commands for every failure scenario.

---

## Design Principles

- **Human-written changelogs.** The skill manages the format; you write the content.
- **Confirm before push.** Every release shows a summary and waits for explicit approval.
- **Ecosystem adapters.** Same flow, different commands. Adding a new ecosystem is one file.
- **Graceful degradation.** Network-dependent steps (push, CI watch) degrade cleanly when unavailable. Steps 1–8 work with just filesystem and git.
- **No tool-specific instructions.** Commands use standard bash — works with any agent that can run shell commands.