release-skills

Name: release-skills
Author: jimliu

byjimliu· 68 skills

Installs

23k

Stars

24k

Forks

2.7k

How to install release-skills?

jimliu/baoyu-skills/release-skills

$npx -y skills add jimliu/baoyu-skills --skill release-skills

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/jimliu/baoyu-skills" --skill "jimliu/baoyu-skills/release-skills"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/jimliu/baoyu-skills" that are relevant to the current task. Run `npx skills add "https://github.com/jimliu/baoyu-skills"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

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

6 picks

Type

Run `npx skills use "https://github.com/jimliu/baoyu-skills" --skill "jimliu/baoyu-skills/release-skills"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/jimliu/baoyu-skills" that are relevant to the current task. Run `npx skills add "https://github.com/jimliu/baoyu-skills"` and select the relevant skills, then follow their instructions.

release-skills

How to install release-skills?

Related

release-skills

How to install release-skills?

Related