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
INLINECODE1	Preview changes without executing
INLINECODE2

Force major version bump | | --minor | Force minor version bump | | --patch | Force patch version bump |

Workflow

Step 1: Detect Project Configuration

1. 1. Check for .releaserc.yml (optional config override)
2. 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)

1. 3. Scan for changelog files using glob patterns:

- CHANGELOG*.md - HISTORY*.md - CHANGES*.md

1. 4. Identify language of each changelog by filename suffix
2. Display detected configuration

Language Detection Rules:

Changelog files follow the pattern CHANGELOG_{LANG}.md or CHANGELOG.{lang}.md, where {lang} / {LANG} is a language or region code.

Pattern	Example	Language
No suffix	INLINECODE20	en (default)
INLINECODE21 (uppercase)

CHANGELOG_CN.md, CHANGELOG_JP.md | Corresponding language |
| .{lang} (lowercase) | CHANGELOG.zh.md, CHANGELOG.ja.md | Corresponding language |
| .{lang-region} | CHANGELOG.zh-CN.md | Corresponding region variant |

Common language codes: zh (Chinese), ja (Japanese), ko (Korean), de (German), fr (French), es (Spanish).

Output Example:
CODEBLOCK0

Step 2: Analyze Changes Since Last Tag

CODEBLOCK1

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 INLINECODE35
• Commit body/footer contains INLINECODE36
• 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):

1. 1. User flag --major/--minor/--patch → Use specified
2. BREAKING CHANGE detected → Major bump (1.x.x → 2.0.0)
3. INLINECODE38 commits present → Minor bump (1.2.x → 1.3.0)
4. Otherwise → Patch bump (1.2.3 → 1.2.4)

Display version change: INLINECODE39

Step 4: Generate Multi-language Changelogs

For each detected changelog file:

1. 1. Identify language from filename suffix
2. 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 <number> --json author --jq '.author.login' - Compare against repo owner (gh repo view --json owner --jq '.owner.login') - If PR author ≠ repo owner → third-party contributor

1. 3. Generate content in that language:

- Section titles in target language - Change descriptions written naturally in target language (not translated) - Date format: YYYY-MM-DD (universal) - Third-party contributions: Append contributor attribution (by @username) to the changelog entry

1. 4. Insert at file head (preserve existing content)

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:

CODEBLOCK2

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):
CODEBLOCK3

Chinese (CHANGELOG.zh.md):
CODEBLOCK4

Japanese (CHANGELOG.ja.md):
CODEBLOCK5

Step 5: Group Changes by Skill/Module

Analyze commits since last tag and group by affected skill/module:

1. 1. Identify changed files per commit
2. Group by skill/module:

- skills/<skill-name>/* → Group under that skill - Root files (CLAUDE.md, etc.) → Group as "project" - Multiple skills in one commit → Split into multiple groups

1. 3. For each group, identify related README updates needed

Example Grouping:
CODEBLOCK6

Step 6: Commit Each Skill/Module Separately

For each skill/module group (in order of changes):

1. 1. 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

1. 2. Stage and commit:

CODEBLOCK7

1. 3. Commit message format:

- Use conventional commit format: <type>(<scope>): <description> - <type>: feat, fix, refactor, docs, perf, etc. - <scope>: skill name or "project" - <description>: Clear, meaningful description of changes

Example Commits:
CODEBLOCK8

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

1. 1. Generate multi-language changelogs (as described in Step 4)
2. 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	INLINECODE53
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:

1. 1. 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, INLINECODE59

1. 2. Push to remote (single select):

- Options: "Yes, push after commit", "No, keep local only"

Example Output Before Confirmation:
CODEBLOCK9

Step 9: Create Release Commit and Tag

After user confirmation:

1. 1. Stage version and changelog files:

CODEBLOCK10

1. 2. Create release commit:

CODEBLOCK11

1. 3. Create tag:

CODEBLOCK12

1. 4. Push if user confirmed (Step 8):

CODEBLOCK13

Note: Do NOT add Co-Authored-By line. This is a release commit, not a code contribution.

Post-Release Output:
CODEBLOCK14

Configuration (.releaserc.yml)

Optional config file in project root to override defaults:

CODEBLOCK15

Dry-Run Mode

When --dry-run is specified:

CODEBLOCK16

Example Usage

CODEBLOCK17

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.