Skip to main content
skill CX Codex

release-please — Claude Code skill: what it does, how to install

Skill for Claude Code, Codex, and Cursor that sets up automated releases via Conventional Commits. Generates release-please configs, version manifests, and GitHub Actions publishing pipelines.

MIT 128 installs ★ 20 updated 2026-11-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bmad-labs/skills --skill release-please -a claude-code
Open on GitHub

What release-please does

Supported in Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. The assistant scans repository manifests like package.json, Cargo.toml, pyproject.toml, or go.mod, determines the language ecosystem, and asks targeted questions about monorepos, release targets, and default branches.

It creates three files: release-please-config.json, .release-please-manifest.json, and .github/workflows/release.yml. If a release workflow already exists, it inspects permissions, concurrency groups, and publication gating on release_created rather than overwriting the entire file.

Projects relying on git submodules across multiple repositories will need multi-repo-git-ops instead, as release-please focuses on single-repo and monorepo workflows.

What it helps with

  • automate semver bumps and changelog creation using Conventional Commits
  • generate release-please-config.json and version manifests for the repository
  • set up GitHub Actions workflows to publish packages to npm, PyPI, or crates.io
  • draft breaking change commit messages with proper footers

Example prompts for the agent

  • Help me draft a Conventional Commit message for the login refactor
  • Set up release-please automation for this Rust library
  • Review our .github/workflows/release.yml and configure npm publishing

How to install release-please

1Skills CLI (Vercel)

npx skills add bmad-labs/skills --skill release-please -a claude-code

2Manually: put the files in place

~/.claude/skills/release-please/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/release-please/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about release-please

How do I install release-please in Claude Code?

Run npx skills add bmad-labs/skills --skill release-please -a claude-code in your terminal.

What does release-please do?

It guides commit message drafting and generates release-please configuration files alongside GitHub Actions pipelines for automated semver releases.

Can release-please manage multi-repo submodule setups?

No, it handles single repositories and monorepos; multi-repository git tasks with submodules require multi-repo-git-ops.

Source text

SKILL.md · MIT
---
name: release-please
description: >-
  Use when the user wants to automate releases, versioning or changelogs with GitHub Actions; set up or configure release-please (pipelines, pre-releases, monorepos); write release-please-compatible Conventional Commits; tag versions or publish to npm, PyPI, crates.io, Maven or Docker automatically; or troubleshoot why a release PR wasn't created — even without naming release-please ("automate my npm releases", "semver automation", "pre-release workflow"). For multi-repo git operations with submodules, use multi-repo-git-ops instead.
---

# release-please

## Overview

[release-please](https://github.com/googleapis/release-please) automates versioning and releases by analyzing Conventional Commit messages:

1. **Push** conventional commits to your default branch
2. **release-please creates/updates a Release PR** with version bump and changelog
3. **Merge** the Release PR to trigger a GitHub Release
4. **Publish** step runs when a release is created (npm, PyPI, crates.io, etc.)

release-please handles version determination, changelog generation, and git tagging. You write good commit messages; it does the rest.

## Commit Message Assistance

When a user asks for help writing a commit message (not setting up a pipeline):

1. **Ask what changed** — "What did you change and why?" (skip if already described)
2. **Suggest the type** — Pick from the type table in the Commit Message Guide below, explain why that type fits
3. **Draft the message** — Write the full commit message (header + body if needed + footers)
4. **Confirm** — Present it for the user to approve or adjust

If the change is breaking, always include a `BREAKING CHANGE:` footer explaining migration impact.

## Pipeline Setup Flow

When a user wants to set up release-please, follow this interactive protocol.

If `.github/workflows/release.yml` (or similar) already exists, read it first, compare against the templates in `references/workflow-templates.md`, and suggest specific improvements rather than replacing it wholesale. Common improvement opportunities: missing concurrency groups, publish not gated on `release_created`, missing idempotent publish check, overly broad permissions.

### Step 1: Detect Project Type

Scan the repository for package manifests:

| File | Release Type |
|------|-------------|
| `package.json` | `node` |
| `pyproject.toml` / `setup.py` | `python` |
| `pom.xml` | `java` |
| `go.mod` | `go` |
| `Cargo.toml` | `rust` |
| `*.gemspec` | `ruby` |
| `composer.json` | `php` |
| `pubspec.yaml` | `dart` |
| `mix.exs` | `elixir` |
| `Chart.yaml` | `helm` |

If multiple manifests exist at the root, ask which is primary. If none found, use `simple`.

### Step 2: Ask Configuration Questions

Ask these questions (skip any already answered or obvious from context):

1. **Is this a monorepo?** (multiple packages in subdirectories)
2. **What is the default branch?** (default: `main`)
3. **Do you need pre-release support?** (manual alpha/beta/rc releases)
4. **Where do you publish?** (npm, GitHub Packages, PyPI, Maven Central, crates.io, Docker, none)
5. **What is the current version?** (check package manifest, default: `0.0.0`)

### Step 3: Generate Files

Create three files based on the answers:

#### release-please-config.json

```json
{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": false,
      "draft": false,
      "prerelease": false,
      "versioning": "default",
      "extra-files": []
    }
  }
}
```

Adjust `release-type` based on detected project type. For monorepos, add multiple entries under `packages` with `component` names.

#### .release-please-manifest.json

```json
{
  ".": "1.0.0"
}
```

Set to the current released version. Use `"0.0.0"` for new projects.

#### .github/workflows/release.yml

For **Node.js → npm public registry** (most common), use this base template:

```yaml
name: Release

on:
  push:
    branches: [main]

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

jobs:
  release-please:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
      version: ${{ steps.release.outputs.version }}
    steps:
      - uses: googleapis/release-please-action@v4
        id: release

  publish:
    needs: release-please
    if: needs.release-please.outputs.release_created == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # required for npm --provenance
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

For **other ecosystems**, see `references/workflow-templates.md` for complete templates including:
- Node.js → GitHub Packages (with idempotent publish check)
- Python → PyPI (trusted publishers)
- Java → Maven Central
- Go (tags only, optional GoReleaser)
- Rust → crates.io
- Docker (build + push with semver tags)
- Monorepo (per-package publish jobs)
- Pre-release pattern (workflow_dispatch with version resolution)

**Always customize:**
- Replace `main` with the actual default branch if different
- Adjust Node version, Python version, Java version, etc.
- Add registry-specific secrets configuration
- If pre-release support is needed, use the pre-release template from `references/workflow-templates.md`

## Configuration Quick Reference

The options you will set most often (all go under `packages.<path>` in `release-please-config.json`):

| Option | Default | Purpose |
|--------|---------|---------|
| `release-type` | — | Package ecosystem (required) |
| `bump-minor-pre-major` | `false` | While < 1.0.0, breaking changes bump minor instead of major |
| `bump-patch-for-minor-pre-major` | `false` | While < 1.0.0, `feat` bumps patch instead of minor |
| `include-v-in-tag` | `true` | Tag as `v1.2.3` vs `1.2.3` |
| `extra-files` | `[]` | Additional files with version strings to update |

For monorepos, add one entry per package path under `packages` (each with a `component` name), list every path in the manifest, and use the component name as the commit scope.

For every option, release types, monorepo setup, and Action inputs/outputs, see `references/config-options.md`.

## Commit Message Guide

release-please reads commit messages on the default branch to decide the version bump and build the changelog. Commits must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): `<type>(<scope>): <description>`, imperative, lowercase, no trailing period.

| Type | Bump |
|------|------|
| `feat` | Minor |
| `fix`, `deps` | Patch |
| `refactor`, `perf`, `test`, `docs`, `style`, `chore`, `build`, `ci` | None (no release on their own) |

Any type with `!` or a `BREAKING CHANGE:` footer bumps **major** (minor while < 1.0.0 if `bump-minor-pre-major` is set). A `Release-As: x.x.x` footer forces a specific version.

```
feat(api)!: redesign authentication flow

BREAKING CHANGE: /auth/login now requires OAuth2 tokens instead of API keys.
```

For the full spec, decision tree, scope guidance, 15+ examples, and anti-patterns, see `references/commit-conventions.md`.

### No AI Co-Author Trailers

**NEVER add `Co-Authored-By` trailers for AI agents** in commit messages. These pollute changelogs and git history.

## Best Practices

### Squash Merges

Configure your repository to use **squash merges** for feature branches. This ensures each PR produces a single conventional commit, keeping the changelog clean. Set the squash commit message to use the PR title (which should be a conventional commit message).

### Permissions

The GitHub Action needs `contents: write` and `pull-requests: write` at minimum. Add `packages: write` or `id-token: write` for publish steps as needed. Use the principle of least privilege — grant permissions per-job, not at workflow level.

### Concurrency

Always set `cancel-in-progress: false` for release workflows. Canceling a release mid-way can leave partial state (tags without releases, PRs in inconsistent state).

### Publish Gating

Never publish in the release-please job itself. Use a separate `publish` job gated on `release_created == 'true'`. This separates concerns and makes retries easier.

### Idempotent Publish

Check if the version already exists in the registry before publishing. This prevents failures on workflow re-runs:

```yaml
- name: Check if version exists
  id: check
  run: |
    PACKAGE_NAME=$(node -p "require('./package.json').name")
    VERSION=$(node -p "require('./package.json').version")
    if npm view "${PACKAGE_NAME}@${VERSION}" version 2>/dev/null; then
      echo "exists=true" >> "$GITHUB_OUTPUT"
    else
      echo "exists=false" >> "$GITHUB_OUTPUT"
    fi
- if: steps.check.outputs.exists == 'false'
  run: npm publish
```

### Bootstrapping Existing Projects

When adding release-please to a project with existing releases:

1. Set `.release-please-manifest.json` to your current version
2. Merge the setup PR with a `chore:` commit
3. release-please will create the next release PR based on subsequent commits
4. Alternatively, use `Release-As: x.x.x` footer to force a starting version

## Troubleshooting

### No Release PR Created

- Ensure commits since the last release include at least one releasable type (`feat`, `fix`, `deps`)
- Check that commits are on the correct branch (must match workflow trigger)
- Verify `release-please-config.json` and manifest exist and are valid JSON
- Check Actions logs for permission errors

### Wrong Version Bump

- Review commit messages — `chore:` won't trigger a release, `feat:` triggers minor
- Check for `BREAKING CHANGE:` footers that may trigger an unexpected major bump
- Use `Release-As: x.x.x` footer to override if needed

### Pre-Release Flow

- Pre-releases use `workflow_dispatch`, not automatic push triggers
- The pre-release identifier is appended to the current version: `1.2.3-alpha.1`
- Use the `next` npm tag (or equivalent) for pre-releases, `latest` for stable
- See the pre-release template in `references/workflow-templates.md`

### Token / Permission Issues

- Default `GITHUB_TOKEN` works for release-please PRs and releases
- Publishing to external registries requires dedicated secrets (`NPM_TOKEN`, etc.)
- GitHub Packages publishing uses `GITHUB_TOKEN` with `packages: write` permission
- For PyPI, use [trusted publishers](https://docs.pypi.org/trusted-publishers/) instead of API tokens

## References

| Reference | Description |
|-----------|-------------|
| `references/commit-conventions.md` | Full Conventional Commits specification with examples and anti-patterns |
| `references/workflow-templates.md` | Complete workflow templates for 9 ecosystems |
| `references/config-options.md` | All configuration options, release types, and Action inputs/outputs |
| [release-please GitHub](https://github.com/googleapis/release-please) | Official documentation |
| [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) | Specification |

© bmad-labs · MIT · bmad-labs/skills

Similar skills

All skills for Git and GitHub →

From the same set12

The whole set →
slides-generator slides-generator builds interactive React and Tailwind presentations, verifies layouts in an automated browser, and bundles everything into a standalone HTML file. CX Codex +1 199installs skill-from-book The skill-from-book Claude Code skill turns a Markdown book into an organized knowledge package for an AI agent. It plans topic files, extracts material, and proposes repeatable workflows. CX Codex +1 183installs book-converter book-converter — a skill for Claude Code that turns EPUB ebooks into structured Markdown documents. Extracts chapters, cleans up formatting via subagents, and generates a unified book with a table of contents. CX Codex +1 147installs bmad-auto bmad-auto orchestrates BMAD development workflows by driving the Phase 4 epic pipeline or routing minor fixes directly into Quick Flow. CX Codex +1 145installs manual-testing manual-testing — a skill for Claude Code, Codex, and Cursor that structures, writes, and reviews manual test cases. Activates when scoping test plans, auditing coverage, or updating suites after feature changes. CX Codex +1 124installs load-docs load-docs — a skill for Claude Code and Codex that loads entire documents and folders into the main agent's context. It reads every chunk directly and replies DONE. CX Codex +1 113installs ultrathink-protocol The ultrathink-protocol Claude Code skill guides root-cause investigations for complex technical failures. It activates after failed fix attempts or before a change when the cause still needs proof. CX Codex +1 106installs multi-repo-git-ops The multi-repo-git-ops Claude Code skill coordinates Git work across a parent repository and its submodules. It handles branch creation, commits, pushes, and submodule pointer updates. CX Codex +1 104installs

Project sponsors

Companies that keep this analytics open