release-skills
Universal release workflow. Auto-detects version files and changelogs. Supports Node.js, Python, Rust, Claude Plugin, GitHub Releases, annotated tags, historical release backfill, and generic projects. Use when user says "release", "发布", "new version", "bump version", "push", "推送", "release notes",
By jimliu · 24,578 installs
npx skills add jimliu/baoyu-skills --skill release-skills
Source repository · Upstream listing
Release Skills
Universal release workflow supporting any project type with multi language changelog.
User Input Tools
When this skill prompts the user, follow this tool selection rule (priority order):
1. Prefer built in user input tools exposed by the current agent runtime — e.g., AskUserQuestion , request user input , clarify , ask user , or any equivalent.
2. Fallback : if no such tool exists, emit a numbered plain text message and ask the user to reply with the chosen number/answer for each question.
3. Batching : if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single question, ask them one at a time in priority order.
Concrete AskUserQuestion references below are examples — substitute the local equivalent in other runtimes.
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
backfill releases Create missing GitHub Releases for existing tags from changelog sections
Workflow
Step 1: Detect Project Configuration
1. Check for .releaserc.yml (optional config override)
If present, inspect whether it defines release hooks
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)
3. Scan for changelog files using glob patterns:
CHANGELOG .md
HISTORY .md
CHANGES .md
4. Identify language of each changelog by filename suffix
5. Detect GitHub release support:
Check whether origin points to GitHub
Check whether gh is installed and authenticated
Check existing releases with gh release list limit 5 when available
6. Display detected configuration
Project Hook Contract :
If .releaserc.yml defines release.hooks , keep the release workflow generic and delegate project specific packaging/publishing to those hooks.
Supported hooks:
Hook Purpose Expected Responsibility
prepare artifact Make one target releasable Validate the target is self contained, sync/embed local dependencies, optionally stage extra files
publish artifact Publish one releasable target Upload the prepared target (or a staged directory if the project uses one), attach version/changelog/tags
Supported placeholders:
Placeholder Meaning
{project root} Absolute path to repository root
{target} Absolute path to the module/skill being released
{artifact dir} Absolute path to a temporary staging directory for this target, when the project uses one
{version} Version selected by the release workflow
{dry run} true or false
{release notes file} Absolute path to a UTF 8 file containing release notes/changelog text
Execution rules:
Keep the skill generic: do not hardcode registry/package manager/project layout details into this SKILL.
If prepare artifact exists, run it once per target before publish related checks that need the final releasable target state.
Write release notes to a temp file and pass that file path to publish artifact ; do not inline multiline changelog text into shell commands.
If hooks are absent, fall back to the default project agnostic release workflow.
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 CHANGELOG.md en (default)
{LANG} (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 :
Step 2: Analyze Changes Since Last Tag
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):
1. User flag major/ minor/ patch → Use specified
2. BREAKING CHANGE detected → Major bump (1.x.x → 2.0.0)
3. feat: commits present → Minor bump (1.2.x → 1.3.0)
4. 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:
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
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
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 :
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):
Chinese (CHANGELOG.zh.md):
Japanese (CHANGELOG.ja.md):
Step 5: Group Changes by Skill/Module
Analyze commits since last tag and group by affected skill/module:
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
3. For each group , identify related README updates needed
Example Grouping :
Step 6: Commit Each Skill/Module Separately
For each skill/module group (in order of changes):
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
2. Stage and commit :
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 :
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. 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)
3. Create release notes file :
Prefer the new version section from CHANGELOG.md
If no English/default changelog exists, use the first detected changelog
Extract only the exact {VERSION} {YYYY MM DD} section through the next
Match both plain version and tag prefixed headings when needed, e.g. 1.2.3 and v1.2.3
Keep breaking changes near the top; if needed, add a short highlight before other sections
Write notes to a UTF 8 temp file and reuse it for annotated tag messages, GitHub Releases, and publish artifact
In normal mode, stop rather than creating an empty tag or GitHub Release when notes cannot be found
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 three questions :
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 , 1.2.3 → 2.0.0
2. Push to remote (single select):
Options: "Yes, push after commit", "No, keep local only"
3. Publish GitHub Release (single select):
Offer this only when GitHub release support is available
Default to "Yes, publish after tag push" when the user also chose push
If the user keeps the release local, do not create or edit a GitHub Release
Example Output Before Confirmation :
Step 9: Create Release Commit and Annotated Tag
After user confirmation:
1. Stage version and changelog files :
2. Create release commit :
3. Create annotated tag :
If .releaserc.yml sets tag.sign: true , use git tag s with the same notes file.
4. Push if user confirmed (Step 8):
Note : Do NOT add Co Authored By line. This is a release commit, not a code contribution.
Step 10: Publish Release Artifacts and GitHub Release
Project artifact publishing and GitHub Releases are separate outputs:
1. Project artifacts :
If release.hooks.publish artifact exists, run it once per prepared target
Pass the same {release notes file} used for the tag and GitHub Release
In dry run mode, pass {dry run}=true and report what would be published
2. GitHub Release :
Run only if the user confirmed remote publishing and GitHub support is available
Ensure the tag exists on the remote before creating the release
Create or update using the extracted notes:
Never inline multiline release notes into shell commands
Post Release Output :
Backfill Existing GitHub Releases
Use this mode when the user asks to backfill historical releases or passes b