Release Skills
Universal release workflow supporting any project type with multi-language changelog.
Quick Start
Just run /release-skills - auto-detects your project configuration.
Supported Projects Project Type Version File Auto-Detected Node.js package.json ✓ Python pyproject.toml ✓ Rust Cargo.toml ✓ Claude Plugin marketplace.json ✓ Generic VERSION / version.txt ✓ Options Flag Description --dry-run Preview changes without executing --major Force major version bump --minor Force minor version bump --patch Force patch version bump Workflow Step 1: Detect Project Configuration Check for .releaserc.yml (optional config override) Auto-detect version file by scanning (priority order): package.json (Node.js) pyproject.toml (Python) Cargo.toml (Rust) marketplace.json or .claude-plugin/marketplace.json (Claude Plugin) VERSION or version.txt (Generic) Scan for changelog files using glob patterns: CHANGELOG.md HISTORY.md CHANGES*.md Identify language of each changelog by filename suffix Display detected configuration
Language Detection Rules:
Filename Pattern Language CHANGELOG.md (no suffix) en (default) CHANGELOG.zh.md / CHANGELOG_CN.md / CHANGELOG.zh-CN.md zh CHANGELOG.ja.md / CHANGELOG_JP.md ja CHANGELOG.ko.md / CHANGELOG_KR.md ko CHANGELOG.de.md / CHANGELOG_DE.md de CHANGELOG.fr.md / CHANGELOG_FR.md fr CHANGELOG.es.md / CHANGELOG_ES.md es CHANGELOG.{lang}.md Corresponding language code
Output Example:
Project detected: Version file: package.json (1.2.3) Changelogs: - CHANGELOG.md (en) - CHANGELOG.zh.md (zh) - CHANGELOG.ja.md (ja)
Step 2: Analyze Changes Since Last Tag LAST_TAG=$(git tag --sort=-v:refname | head -1) git log ${LAST_TAG}..HEAD --oneline git diff ${LAST_TAG}..HEAD --stat
Categorize by conventional commit types:
Type Description feat New features fix Bug fixes docs Documentation refactor Code refactoring perf Performance improvements test Test changes style Formatting, styling chore Maintenance (skip in changelog)
Breaking Change Detection:
Commit message starts with BREAKING CHANGE Commit body/footer contains BREAKING CHANGE: Removed public APIs, renamed exports, changed interfaces
If breaking changes detected, warn user: "Breaking changes detected. Consider major version bump (--major flag)."
Step 3: Determine Version Bump
Rules (in priority order):
User flag --major/--minor/--patch → Use specified BREAKING CHANGE detected → Major bump (1.x.x → 2.0.0) feat: commits present → Minor bump (1.2.x → 1.3.0) Otherwise → Patch bump (1.2.3 → 1.2.4)
Display version change: 1.2.3 → 1.3.0
Step 4: Generate Multi-language Changelogs
For each detected changelog file:
Identify language from filename suffix
Detect third-party contributors:
Check merge commits: git log ${LAST_TAG}..HEAD --merges --pretty=format:"%H %s"
For each merged PR, identify the PR author via gh pr view
Section Title Translations (built-in):
Type en zh ja ko de fr es feat Features 新功能 新機能 새로운 기능 Funktionen Fonctionnalités Características fix Fixes 修复 修正 수정 Fehlerbehebungen Corrections Correcciones docs Documentation 文档 ドキュメント 문서 Dokumentation Documentation Documentación refactor Refactor 重构 リファクタリング 리팩토링 Refactoring Refactorisation Refactorización perf Performance 性能优化 パフォーマンス 성능 Leistung Performance Rendimiento breaking Breaking Changes 破坏性变更 破壊的変更 주요 변경사항 Breaking Changes Changements majeurs Cambios importantes
Changelog Format:
{VERSION} -
Features
- Description of new feature
- Description of third-party contribution (by @username)
Fixes
- Description of fix
Documentation
- Description of docs changes
Only include sections that have changes. Omit empty sections.
Third-Party Attribution Rules:
Only add (by @username) for contributors who are NOT the repo owner Use GitHub username with @ prefix Place at the end of the changelog entry line Apply to all languages consistently (always use (by @username) format, not translated)
Multi-language Example:
English (CHANGELOG.md):
1.3.0 - 2026-01-22
Features
- Add user authentication module (by @contributor1)
- Support OAuth2 login
Fixes
- Fix memory leak in connection pool
Chinese (CHANGELOG.zh.md):
1.3.0 - 2026-01-22
新功能
- 新增用户认证模块 (by @contributor1)
- 支持 OAuth2 登录
修复
- 修复连接池内存泄漏问题
Japanese (CHANGELOG.ja.md):
1.3.0 - 2026-01-22
新機能
- ユーザー認証モジュールを追加 (by @contributor1)
- OAuth2 ログインをサポート
修正
- コネクションプールのメモリリークを修正
Step 5: Group Changes by Skill/Module
Analyze commits since last tag and group by affected skill/module:
Identify changed files per commit
Group by skill/module:
skills/
Example Grouping:
baoyu-cover-image: - feat: add new style options - fix: handle transparent backgrounds → README updates: options table
baoyu-comic: - refactor: improve panel layout algorithm → No README updates needed
project: - docs: update CLAUDE.md architecture section
Step 6: Commit Each Skill/Module Separately
For each skill/module group (in order of changes):
Check README updates needed:
Scan README*.md for mentions of this skill/module Verify options/flags documented correctly Update usage examples if syntax changed Update feature descriptions if behavior changed
Stage and commit:
git add skills/
Commit message format:
Use conventional commit format:
Example Commits:
git commit -m "feat(baoyu-cover-image): add watercolor and minimalist styles" git commit -m "fix(baoyu-comic): improve panel layout for long dialogues" git commit -m "docs(project): update architecture documentation"
Common README Updates Needed:
Change Type README Section to Check New options/flags Options table, usage examples Renamed options Options table, usage examples New features Feature description, examples Breaking changes Migration notes, deprecation warnings Restructured internals Architecture section (if exposed to users) Step 7: Generate Changelog and Update Version Generate multi-language changelogs (as described in Step 4) Update version file: Read version file (JSON/TOML/text) Update version number Write back (preserve formatting)
Version Paths by File Type:
File Path package.json $.version pyproject.toml project.version Cargo.toml package.version marketplace.json $.metadata.version VERSION / version.txt Direct content Step 8: User Confirmation
Before creating the release commit, ask user to confirm:
Use AskUserQuestion with two questions:
Version bump (single select):
Show recommended version based on Step 3 analysis Options: recommended (with label), other semver options Example: 1.2.3 → 1.3.0 (Recommended), 1.2.3 → 1.2.4, 1.2.3 → 2.0.0
Push to remote (single select):
Options: "Yes, push after commit", "No, keep local only"
Example Output Before Confirmation:
Commits created: 1. feat(baoyu-cover-image): add watercolor and minimalist styles 2. fix(baoyu-comic): improve panel layout for long dialogues 3. docs(project): update architecture documentation
Changelog preview (en): ## 1.3.0 - 2026-01-22 ### Features - Add watercolor and minimalist styles to cover-image ### Fixes - Improve panel layout for long dialogues in comic
Ready to create release commit and tag.
Step 9: Create Release Commit and Tag
After user confirmation:
Stage version and changelog files:
git add
Create release commit:
git commit -m "chore: release v{VERSION}"
Create tag:
git tag v{VERSION}
Push if user confirmed (Step 8):
git push origin main git push origin v{VERSION}
Note: Do NOT add Co-Authored-By line. This is a release commit, not a code contribution.
Post-Release Output:
Release v1.3.0 created.
Commits: 1. feat(baoyu-cover-image): add watercolor and minimalist styles 2. fix(baoyu-comic): improve panel layout for long dialogues 3. docs(project): update architecture documentation 4. chore: release v1.3.0
Tag: v1.3.0 Status: Pushed to origin # or "Local only - run git push when ready"
Configuration (.releaserc.yml)
Optional config file in project root to override defaults:
.releaserc.yml - Optional configuration
Version file (auto-detected if not specified)
version: file: package.json path: $.version # JSONPath for JSON, dotted path for TOML
Changelog files (auto-detected if not specified)
changelog: files: - path: CHANGELOG.md lang: en - path: CHANGELOG.zh.md lang: zh - path: CHANGELOG.ja.md lang: ja
# Section mapping (conventional commit type → changelog section) # Use null to skip a type in changelog sections: feat: Features fix: Fixes docs: Documentation refactor: Refactor perf: Performance test: Tests chore: null
Commit message format
commit: message: "chore: release v{version}"
Tag format
tag: prefix: v # Results in v1.0.0 sign: false
Additional files to include in release commit
include: - README.md - package.json
Dry-Run Mode
When --dry-run is specified:
=== DRY RUN MODE ===
Project detected: Version file: package.json (1.2.3) Changelogs: CHANGELOG.md (en), CHANGELOG.zh.md (zh)
Last tag: v1.2.3 Proposed version: v1.3.0
Changes grouped by skill/module: baoyu-cover-image: - feat: add watercolor style - feat: add minimalist style → Commit: feat(baoyu-cover-image): add watercolor and minimalist styles → README updates: options table
baoyu-comic: - fix: panel layout for long dialogues → Commit: fix(baoyu-comic): improve panel layout for long dialogues → No README updates
Changelog preview (en): ## 1.3.0 - 2026-01-22 ### Features - Add watercolor and minimalist styles to cover-image ### Fixes - Improve panel layout for long dialogues in comic
Changelog preview (zh): ## 1.3.0 - 2026-01-22 ### 新功能 - 为 cover-image 添加水彩和极简风格 ### 修复 - 改进 comic 长对话的面板布局
Commits to create: 1. feat(baoyu-cover-image): add watercolor and minimalist styles 2. fix(baoyu-comic): improve panel layout for long dialogues 3. chore: release v1.3.0
No changes made. Run without --dry-run to execute.
Example Usage /release-skills # Auto-detect version bump /release-skills --dry-run # Preview only /release-skills --minor # Force minor bump /release-skills --patch # Force patch bump /release-skills --major # Force major bump (with confirmation)
When to Use
Trigger this skill when user requests:
"release", "发布", "create release", "new version", "新版本" "bump version", "update version", "更新版本" "prepare release" "push to remote" (with uncommitted changes)
Important: If user says "just push" or "直接 push" with uncommitted changes, STILL follow all steps above first.