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
npx skills add bmad-labs/skills --skill release-please -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/release-please/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/release-please/
1Skills CLI (Vercel)
npx skills add bmad-labs/skills --skill release-please -a codex2Manually: put the files in place
.agents/skills/release-please/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bmad-labs/skills --skill release-please -a cursor2Manually: put the files in place
.cursor/skills/release-please/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bmad-labs/skills skills/release-please2Manually: put the files in place
.github/skills/release-please/SKILL.md1Skills CLI (Vercel)
npx skills add bmad-labs/skills --skill release-please -a gemini-cli2Platform CLI
gemini skills install https://github.com/bmad-labs/skills --path skills/release-pleaseManually: put the files in place
.devin/skills/release-please/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add bmad-labs/skills --skill release-please -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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