1---
2name: release-skills
3description: 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", "GitHub Release", or "回填 Release".
4---
5 
6# Release Skills
7 
8Universal release workflow supporting any project type with multi-language changelog.
9 
10## User Input Tools
11 
12When this skill prompts the user, follow this tool-selection rule (priority order):
13 
141. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
152. **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.
163. **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.
17 
18Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
19 
20## Quick Start
21 
22Just run `/release-skills` - auto-detects your project configuration.
23 
24## Supported Projects
25 
26| Project Type | Version File | Auto-Detected |
27|--------------|--------------|---------------|
28| Node.js | package.json | ✓ |
29| Python | pyproject.toml | ✓ |
30| Rust | Cargo.toml | ✓ |
31| Claude Plugin | marketplace.json | ✓ |
32| Generic | VERSION / version.txt | ✓ |
33 
34## Options
35 
36| Flag | Description |
37|------|-------------|
38| `--dry-run` | Preview changes without executing |
39| `--major` | Force major version bump |
40| `--minor` | Force minor version bump |
41| `--patch` | Force patch version bump |
42| `--backfill-releases` | Create missing GitHub Releases for existing tags from changelog sections |
43 
44## Workflow
45 
46### Step 1: Detect Project Configuration
47 
481. Check for `.releaserc.yml` (optional config override)
49   - If present, inspect whether it defines release hooks
502. Auto-detect version file by scanning (priority order):
51   - `package.json` (Node.js)
52   - `pyproject.toml` (Python)
53   - `Cargo.toml` (Rust)
54   - `marketplace.json` or `.claude-plugin/marketplace.json` (Claude Plugin)
55   - `VERSION` or `version.txt` (Generic)
563. Scan for changelog files using glob patterns:
57   - `CHANGELOG*.md`
58   - `HISTORY*.md`
59   - `CHANGES*.md`
604. Identify language of each changelog by filename suffix
615. Detect GitHub release support:
62   - Check whether `origin` points to GitHub
63   - Check whether `gh` is installed and authenticated
64   - Check existing releases with `gh release list --limit 5` when available
656. Display detected configuration
66 
67**Project Hook Contract**:
68 
69If `.releaserc.yml` defines `release.hooks`, keep the release workflow generic and delegate project-specific packaging/publishing to those hooks.
70 
71Supported hooks:
72 
73| Hook | Purpose | Expected Responsibility |
74|------|---------|-------------------------|
75| `prepare_artifact` | Make one target releasable | Validate the target is self-contained, sync/embed local dependencies, optionally stage extra files |
76| `publish_artifact` | Publish one releasable target | Upload the prepared target (or a staged directory if the project uses one), attach version/changelog/tags |
77 
78Supported placeholders:
79 
80| Placeholder | Meaning |
81|-------------|---------|
82| `{project_root}` | Absolute path to repository root |
83| `{target}` | Absolute path to the module/skill being released |
84| `{artifact_dir}` | Absolute path to a temporary staging directory for this target, when the project uses one |
85| `{version}` | Version selected by the release workflow |
86| `{dry_run}` | `true` or `false` |
87| `{release_notes_file}` | Absolute path to a UTF-8 file containing release notes/changelog text |
88 
89Execution rules:
90- Keep the skill generic: do not hardcode registry/package-manager/project layout details into this SKILL.
91- If `prepare_artifact` exists, run it once per target before publish-related checks that need the final releasable target state.
92- Write release notes to a temp file and pass that file path to `publish_artifact`; do not inline multiline changelog text into shell commands.
93- If hooks are absent, fall back to the default project-agnostic release workflow.
94 
95**Language Detection Rules**:
96 
97Changelog files follow the pattern `CHANGELOG_{LANG}.md` or `CHANGELOG.{lang}.md`, where `{lang}` / `{LANG}` is a language or region code.
98 
99| Pattern | Example | Language |
100|---------|---------|----------|
101| No suffix | `CHANGELOG.md` | en (default) |
102| `_{LANG}` (uppercase) | `CHANGELOG_CN.md`, `CHANGELOG_JP.md` | Corresponding language |
103| `.{lang}` (lowercase) | `CHANGELOG.zh.md`, `CHANGELOG.ja.md` | Corresponding language |
104| `.{lang-region}` | `CHANGELOG.zh-CN.md` | Corresponding region variant |
105 
106Common language codes: `zh` (Chinese), `ja` (Japanese), `ko` (Korean), `de` (German), `fr` (French), `es` (Spanish).
107 
108**Output Example**:
109```
110Project detected:
111  Version file: package.json (1.2.3)
112  Changelogs:
113    - CHANGELOG.md (en)
114    - CHANGELOG.zh.md (zh)
115    - CHANGELOG.ja.md (ja)
116```
117 
118### Step 2: Analyze Changes Since Last Tag
119 
120```bash
121LAST_TAG=$(git tag --sort=-v:refname | head -1)
122git log ${LAST_TAG}..HEAD --oneline
123git diff ${LAST_TAG}..HEAD --stat
124```
125 
126Categorize by conventional commit types:
127 
128| Type | Description |
129|------|-------------|
130| feat | New features |
131| fix | Bug fixes |
132| docs | Documentation |
133| refactor | Code refactoring |
134| perf | Performance improvements |
135| test | Test changes |
136| style | Formatting, styling |
137| chore | Maintenance (skip in changelog) |
138 
139**Breaking Change Detection**:
140- Commit message starts with `BREAKING CHANGE`
141- Commit body/footer contains `BREAKING CHANGE:`
142- Removed public APIs, renamed exports, changed interfaces
143 
144If breaking changes detected, warn user: "Breaking changes detected. Consider major version bump (--major flag)."
145 
146### Step 3: Determine Version Bump
147 
148Rules (in priority order):
1491. User flag `--major/--minor/--patch` → Use specified
1502. BREAKING CHANGE detected → Major bump (1.x.x → 2.0.0)
1513. `feat:` commits present → Minor bump (1.2.x → 1.3.0)
1524. Otherwise → Patch bump (1.2.3 → 1.2.4)
153 
154Display version change: `1.2.3 → 1.3.0`
155 
156### Step 4: Generate Multi-language Changelogs
157 
158For each detected changelog file:
159 
1601. **Identify language** from filename suffix
1612. **Detect third-party contributors**:
162   - Check merge commits: `git log ${LAST_TAG}..HEAD --merges --pretty=format:"%H %s"`
163   - For each merged PR, identify the PR author via `gh pr view <number> --json author --jq '.author.login'`
164   - Compare against repo owner (`gh repo view --json owner --jq '.owner.login'`)
165   - If PR author ≠ repo owner → third-party contributor
1663. **Generate content in that language**:
167   - Section titles in target language
168   - Change descriptions written naturally in target language (not translated)
169   - Date format: YYYY-MM-DD (universal)
170   - **Third-party contributions**: Append contributor attribution `(by @username)` to the changelog entry
1714. **Insert at file head** (preserve existing content)
172 
173**Section Title Translations** (built-in):
174 
175| Type | en | zh | ja | ko | de | fr | es |
176|------|----|----|----|----|----|----|-----|
177| feat | Features | 新功能 | 新機能 | 새로운 기능 | Funktionen | Fonctionnalités | Características |
178| fix | Fixes | 修复 | 修正 | 수정 | Fehlerbehebungen | Corrections | Correcciones |
179| docs | Documentation | 文档 | ドキュメント | 문서 | Dokumentation | Documentation | Documentación |
180| refactor | Refactor | 重构 | リファクタリング | 리팩토링 | Refactoring | Refactorisation | Refactorización |
181| perf | Performance | 性能优化 | パフォーマンス | 성능 | Leistung | Performance | Rendimiento |
182| breaking | Breaking Changes | 破坏性变更 | 破壊的変更 | 주요 변경사항 | Breaking Changes | Changements majeurs | Cambios importantes |
183 
184**Changelog Format**:
185 
186```markdown
187## {VERSION} - {YYYY-MM-DD}
188 
189### Features
190- Description of new feature
191- Description of third-party contribution (by @username)
192 
193### Fixes
194- Description of fix
195 
196### Documentation
197- Description of docs changes
198```
199 
200Only include sections that have changes. Omit empty sections.
201 
202**Third-Party Attribution Rules**:
203- Only add `(by @username)` for contributors who are NOT the repo owner
204- Use GitHub username with `@` prefix
205- Place at the end of the changelog entry line
206- Apply to all languages consistently (always use `(by @username)` format, not translated)
207 
208**Multi-language Example**:
209 
210English (CHANGELOG.md):
211```markdown
212## 1.3.0 - 2026-01-22
213 
214### Features
215- Add user authentication module (by @contributor1)
216- Support OAuth2 login
217 
218### Fixes
219- Fix memory leak in connection pool
220```
221 
222Chinese (CHANGELOG.zh.md):
223```markdown
224## 1.3.0 - 2026-01-22
225 
226### 新功能
227- 新增用户认证模块 (by @contributor1)
228- 支持 OAuth2 登录
229 
230### 修复
231- 修复连接池内存泄漏问题
232```
233 
234Japanese (CHANGELOG.ja.md):
235```markdown
236## 1.3.0 - 2026-01-22
237 
238### 新機能
239- ユーザー認証モジュールを追加 (by @contributor1)
240- OAuth2 ログインをサポート
241 
242### 修正
243- コネクションプールのメモリリークを修正
244```
245 
246### Step 5: Group Changes by Skill/Module
247 
248Analyze commits since last tag and group by affected skill/module:
249 
2501. **Identify changed files** per commit
2512. **Group by skill/module**:
252   - `skills/<skill-name>/*` → Group under that skill
253   - Root files (CLAUDE.md, etc.) → Group as "project"
254   - Multiple skills in one commit → Split into multiple groups
2553. **For each group**, identify related README updates needed
256 
257**Example Grouping**:
258```
259baoyu-cover-image:
260  - feat: add new style options
261  - fix: handle transparent backgrounds
262  → README updates: options table
263 
264baoyu-comic:
265  - refactor: improve panel layout algorithm
266  → No README updates needed
267 
268project:
269  - docs: update CLAUDE.md architecture section
270```
271 
272### Step 6: Commit Each Skill/Module Separately
273 
274For each skill/module group (in order of changes):
275 
2761. **Check README updates needed**:
277   - Scan `README*.md` for mentions of this skill/module
278   - Verify options/flags documented correctly
279   - Update usage examples if syntax changed
280   - Update feature descriptions if behavior changed
281 
2822. **Stage and commit**:
283   ```bash
284   git add skills/<skill-name>/*
285   git add README.md README.zh.md  # If updated for this skill
286   git commit -m "<type>(<skill-name>): <meaningful description>"
287   ```
288 
2893. **Commit message format**:
290   - Use conventional commit format: `<type>(<scope>): <description>`
291   - `<type>`: feat, fix, refactor, docs, perf, etc.
292   - `<scope>`: skill name or "project"
293   - `<description>`: Clear, meaningful description of changes
294 
295**Example Commits**:
296```bash
297git commit -m "feat(baoyu-cover-image): add watercolor and minimalist styles"
298git commit -m "fix(baoyu-comic): improve panel layout for long dialogues"
299git commit -m "docs(project): update architecture documentation"
300```
301 
302**Common README Updates Needed**:
303| Change Type | README Section to Check |
304|-------------|------------------------|
305| New options/flags | Options table, usage examples |
306| Renamed options | Options table, usage examples |
307| New features | Feature description, examples |
308| Breaking changes | Migration notes, deprecation warnings |
309| Restructured internals | Architecture section (if exposed to users) |
310 
311### Step 7: Generate Changelog and Update Version
312 
3131. **Generate multi-language changelogs** (as described in Step 4)
3142. **Update version file**:
315   - Read version file (JSON/TOML/text)
316   - Update version number
317   - Write back (preserve formatting)
3183. **Create release notes file**:
319   - Prefer the new version section from `CHANGELOG.md`
320   - If no English/default changelog exists, use the first detected changelog
321   - Extract only the exact `## {VERSION} - {YYYY-MM-DD}` section through the next `##`
322   - Match both plain version and tag-prefixed headings when needed, e.g. `1.2.3` and `v1.2.3`
323   - Keep breaking changes near the top; if needed, add a short highlight before other sections
324   - Write notes to a UTF-8 temp file and reuse it for annotated tag messages, GitHub Releases, and `publish_artifact`
325   - In normal mode, stop rather than creating an empty tag or GitHub Release when notes cannot be found
326 
327**Version Paths by File Type**:
328 
329| File | Path |
330|------|------|
331| package.json | `$.version` |
332| pyproject.toml | `project.version` |
333| Cargo.toml | `package.version` |
334| marketplace.json | `$.metadata.version` |
335| VERSION / version.txt | Direct content |
336 
337### Step 8: User Confirmation
338 
339Before creating the release commit, ask user to confirm:
340 
341**Use AskUserQuestion with three questions**:
342 
3431. **Version bump** (single select):
344   - Show recommended version based on Step 3 analysis
345   - Options: recommended (with label), other semver options
346   - Example: `1.2.3 → 1.3.0 (Recommended)`, `1.2.3 → 1.2.4`, `1.2.3 → 2.0.0`
347 
3482. **Push to remote** (single select):
349   - Options: "Yes, push after commit", "No, keep local only"
350 
3513. **Publish GitHub Release** (single select):
352   - Offer this only when GitHub release support is available
353   - Default to "Yes, publish after tag push" when the user also chose push
354   - If the user keeps the release local, do not create or edit a GitHub Release
355 
356**Example Output Before Confirmation**:
357```
358Commits created:
359  1. feat(baoyu-cover-image): add watercolor and minimalist styles
360  2. fix(baoyu-comic): improve panel layout for long dialogues
361  3. docs(project): update architecture documentation
362 
363Changelog preview (en):
364  ## 1.3.0 - 2026-01-22
365  ### Features
366  - Add watercolor and minimalist styles to cover-image
367  ### Fixes
368  - Improve panel layout for long dialogues in comic
369 
370Release notes source: CHANGELOG.md#1.3.0
371Ready to create release commit, annotated tag, and GitHub Release.
372```
373 
374### Step 9: Create Release Commit and Annotated Tag
375 
376After user confirmation:
377 
3781. **Stage version and changelog files**:
379   ```bash
380   git add <version-file>
381   git add CHANGELOG*.md
382   ```
383 
3842. **Create release commit**:
385   ```bash
386   git commit -m "chore: release v{VERSION}"
387   ```
388 
3893. **Create annotated tag**:
390   ```bash
391   git tag -a v{VERSION} -F <release-notes-file>
392   ```
393   If `.releaserc.yml` sets `tag.sign: true`, use `git tag -s` with the same notes file.
394 
3954. **Push if user confirmed** (Step 8):
396   ```bash
397   git push origin main
398   git push origin v{VERSION}
399   ```
400 
401**Note**: Do NOT add Co-Authored-By line. This is a release commit, not a code contribution.
402 
403### Step 10: Publish Release Artifacts and GitHub Release
404 
405Project artifact publishing and GitHub Releases are separate outputs:
406 
4071. **Project artifacts**:
408   - If `release.hooks.publish_artifact` exists, run it once per prepared target
409   - Pass the same `{release_notes_file}` used for the tag and GitHub Release
410   - In dry-run mode, pass `{dry_run}=true` and report what would be published
411 
4122. **GitHub Release**:
413   - Run only if the user confirmed remote publishing and GitHub support is available
414   - Ensure the tag exists on the remote before creating the release
415   - Create or update using the extracted notes:
416     ```bash
417     if gh release view v{VERSION} >/dev/null 2>&1; then
418       gh release edit v{VERSION} --title "v{VERSION}" --notes-file <release-notes-file>
419     else
420       gh release create v{VERSION} --title "v{VERSION}" --notes-file <release-notes-file> --verify-tag
421     fi
422     ```
423   - Never inline multiline release notes into shell commands
424 
425**Post-Release Output**:
426```
427Release v1.3.0 created.
428 
429Commits:
430  1. feat(baoyu-cover-image): add watercolor and minimalist styles
431  2. fix(baoyu-comic): improve panel layout for long dialogues
432  3. docs(project): update architecture documentation
433  4. chore: release v1.3.0
434 
435Tag: v1.3.0
436Tag type: annotated
437GitHub Release: published  # or "skipped/local only"
438Status: Pushed to origin  # or "Local only - run git push when ready"
439```
440 
441## Backfill Existing GitHub Releases
442 
443Use this mode when the user asks to backfill historical releases or passes `--backfill-releases`.
444 
4451. Do not bump versions, edit changelogs, or create release commits.
4462. List existing tags in version order and detect missing releases:
447   ```bash
448   git tag --sort=v:refname
449   gh release view <tag>
450   ```
4513. For each tag without a GitHub Release:
452   - Normalize the changelog lookup by stripping the configured tag prefix, e.g. `v1.2.3` -> `1.2.3`
453   - Extract the matching section from `CHANGELOG.md`; fall back to the first matching changelog file
454   - Skip or ask before publishing if no matching changelog section exists
455   - Create the release with:
456     ```bash
457     gh release create <tag> --title "<tag>" --notes-file <release-notes-file> --verify-tag
458     ```
4594. Detect lightweight tags with `git cat-file -t <tag>` (`commit` means lightweight, `tag` means annotated).
4605. Do not rewrite public lightweight tags by default. Converting an existing remote tag to an annotated tag requires explicit user confirmation because it rewrites a published reference.
461 
462## Configuration (.releaserc.yml)
463 
464Optional config file in project root to override defaults:
465 
466```yaml
467# .releaserc.yml - Optional configuration
468 
469# Version file (auto-detected if not specified)
470version:
471  file: package.json
472  path: $.version  # JSONPath for JSON, dotted path for TOML
473 
474# Changelog files (auto-detected if not specified)
475changelog:
476  files:
477    - path: CHANGELOG.md
478      lang: en
479    - path: CHANGELOG.zh.md
480      lang: zh
481    - path: CHANGELOG.ja.md
482      lang: ja
483 
484  # Section mapping (conventional commit type → changelog section)
485  # Use null to skip a type in changelog
486  sections:
487    feat: Features
488    fix: Fixes
489    docs: Documentation
490    refactor: Refactor
491    perf: Performance
492    test: Tests
493    chore: null
494 
495# Commit message format
496commit:
497  message: "chore: release v{version}"
498 
499# Tag format
500tag:
501  prefix: v  # Results in v1.0.0
502  sign: false
503 
504# Additional files to include in release commit
505include:
506  - README.md
507  - package.json
508```
509 
510## Dry-Run Mode
511 
512When `--dry-run` is specified:
513 
514```
515=== DRY RUN MODE ===
516 
517Project detected:
518  Version file: package.json (1.2.3)
519  Changelogs: CHANGELOG.md (en), CHANGELOG.zh.md (zh)
520 
521Last tag: v1.2.3
522Proposed version: v1.3.0
523 
524Changes grouped by skill/module:
525  baoyu-cover-image:
526    - feat: add watercolor style
527    - feat: add minimalist style
528    → Commit: feat(baoyu-cover-image): add watercolor and minimalist styles
529    → README updates: options table
530 
531  baoyu-comic:
532    - fix: panel layout for long dialogues
533    → Commit: fix(baoyu-comic): improve panel layout for long dialogues
534    → No README updates
535 
536Changelog preview (en):
537  ## 1.3.0 - 2026-01-22
538  ### Features
539  - Add watercolor and minimalist styles to cover-image
540  ### Fixes
541  - Improve panel layout for long dialogues in comic
542 
543Changelog preview (zh):
544  ## 1.3.0 - 2026-01-22
545  ### 新功能
546  - 为 cover-image 添加水彩和极简风格
547  ### 修复
548  - 改进 comic 长对话的面板布局
549 
550Commits to create:
551  1. feat(baoyu-cover-image): add watercolor and minimalist styles
552  2. fix(baoyu-comic): improve panel layout for long dialogues
553  3. chore: release v1.3.0
554 
555No changes made. Run without --dry-run to execute.
556```
557 
558## Example Usage
559 
560```
561/release-skills              # Auto-detect version bump
562/release-skills --dry-run    # Preview only
563/release-skills --minor      # Force minor bump
564/release-skills --patch      # Force patch bump
565/release-skills --major      # Force major bump (with confirmation)
566/release-skills --backfill-releases  # Create missing GitHub Releases for existing tags
567```
568 
569## When to Use
570 
571Trigger this skill when user requests:
572- "release", "发布", "create release", "new version", "新版本"
573- "bump version", "update version", "更新版本"
574- "prepare release"
575- "release notes", "GitHub Release", "回填 Release"
576- "push to remote" (with uncommitted changes)
577 
578**Important**: If user says "just push" or "直接 push" with uncommitted changes, STILL follow all steps above first.
579