release-skills

Release Skills

通用發布工作流程，支援任何專案類型與多語言更新日誌。

使用者輸入工具

當此技能提示使用者時，請依下列工具選擇規則（優先順序）：

優先使用當前代理執行環境提供的內建使用者輸入工具，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
備援：若無此類工具，則輸出編號的純文字訊息，並要求使用者回覆對應的數字/答案。
批次處理：若工具支援單次呼叫多個問題，則將所有適用問題合併為一次呼叫；若僅支援單一問題，則依優先順序逐一詢問。

以下具體的 AskUserQuestion 參考僅為範例——在其他執行環境中請替換為當地等效工具。

快速開始

直接執行 /release-skills - 自動偵測您的專案設定。

支援的專案類型

專案類型	版本檔案	自動偵測
Node.js	package.json	✓
Python	pyproject.toml	✓
Rust	Cargo.toml	✓
Claude Plugin	marketplace.json	✓
通用	VERSION / version.txt	✓

選項

旗標	說明
`--dry-run`	預覽變更但不執行
`--major`	強制主版本號升級
`--minor`	強制次版本號升級
`--patch`	強制修訂版本號升級
`--backfill-releases`	根據更新日誌區段，為現有標籤建立遺失的 GitHub Releases

工作流程

步驟 1：偵測專案設定

檢查 .releaserc.yml（選擇性設定覆蓋）
- 若存在，檢查是否定義了 release hooks
自動偵測版本檔案（依優先順序掃描）：
- package.json (Node.js)
- pyproject.toml (Python)
- Cargo.toml (Rust)
- marketplace.json 或 .claude-plugin/marketplace.json (Claude Plugin)
- VERSION 或 version.txt (通用)
使用 glob 模式掃描更新日誌檔案：
- CHANGELOG*.md
- HISTORY*.md
- CHANGES*.md
根據檔案名稱後綴識別每個更新日誌的語言
偵測 GitHub Release 支援：
- 檢查 origin 是否指向 GitHub
- 檢查 gh 是否已安裝並通過驗證
- 若可用，使用 gh release list --limit 5 檢查現有 Releases
顯示偵測到的設定

專案 Hook 合約：

若 .releaserc.yml 定義了 release.hooks，則保持發布工作流程通用，並將專案特定的打包/發布委派給這些 hooks。

支援的 hooks：

Hook	目的	預期職責
`prepare_artifact`	使一個目標可發布	驗證目標是否自包含，同步/嵌入本地依賴，選擇性暫存額外檔案
`publish_artifact`	發布一個可發布目標	上傳準備好的目標（或專案使用的暫存目錄），附加版本/更新日誌/標籤

支援的佔位符：

佔位符	意義
`{project_root}`	儲存庫根目錄的絕對路徑
`{target}`	正在發布的模組/技能的絕對路徑
`{artifact_dir}`	當專案使用暫存目錄時，該目標的臨時暫存目錄絕對路徑
`{version}`	發布工作流程選擇的版本
`{dry_run}`	`true` 或 `false`
`{release_notes_file}`	包含發布說明/更新日誌文字的 UTF-8 檔案絕對路徑

執行規則：

保持技能通用：不要將註冊表/套件管理器/專案佈局細節硬編碼到此 SKILL 中。
若 prepare_artifact 存在，則在需要最終可發布目標狀態的發布相關檢查之前，對每個目標執行一次。
將發布說明寫入暫存檔案，並將該檔案路徑傳遞給 publish_artifact；不要將多行更新日誌文字內嵌到 shell 命令中。
若 hooks 不存在，則回退到預設的與專案無關的發布工作流程。

語言偵測規則：

更新日誌檔案遵循模式 CHANGELOG_{LANG}.md 或 CHANGELOG.{lang}.md，其中 {lang} / {LANG} 是語言或地區代碼。

模式	範例	語言
無後綴	`CHANGELOG.md`	en (預設)
`_{LANG}` (大寫)	`CHANGELOG_CN.md`, `CHANGELOG_JP.md`	對應語言
`.{lang}` (小寫)	`CHANGELOG.zh.md`, `CHANGELOG.ja.md`	對應語言
`.{lang-region}`	`CHANGELOG.zh-CN.md`	對應地區變體

常見語言代碼：zh (中文), ja (日文), ko (韓文), de (德文), fr (法文), es (西班牙文)。

輸出範例：

Project detected:
  Version file: package.json (1.2.3)
  Changelogs:
    - CHANGELOG.md (en)
    - CHANGELOG.zh.md (zh)
    - CHANGELOG.ja.md (ja)

步驟 2：分析自上次標籤以來的變更

LAST_TAG=$(git tag --sort=-v:refname | head -1)
git log ${LAST_TAG}..HEAD --oneline
git diff ${LAST_TAG}..HEAD --stat

依慣例提交類型分類：

類型	說明
feat	新功能
fix	錯誤修正
docs	文件
refactor	程式碼重構
perf	效能改善
test	測試變更
style	格式、樣式
chore	維護（在更新日誌中跳過）

破壞性變更偵測：

提交訊息以 BREAKING CHANGE 開頭
提交內文/頁尾包含 BREAKING CHANGE:
移除公開 API、重新命名匯出、變更介面

若偵測到破壞性變更，警告使用者：「偵測到破壞性變更。請考慮主版本號升級（--major 旗標）。」

步驟 3：決定版本升級

規則（依優先順序）：

使用者旗標 --major/--minor/--patch → 使用指定的版本
偵測到 BREAKING CHANGE → 主版本升級（1.x.x → 2.0.0）
存在 feat: 提交 → 次版本升級（1.2.x → 1.3.0）
否則 → 修訂版本升級（1.2.3 → 1.2.4）

顯示版本變更：1.2.3 → 1.3.0

步驟 4：產生多語言更新日誌

對於每個偵測到的更新日誌檔案：

從檔案名稱後綴識別語言
偵測第三方貢獻者：
- 檢查合併提交：git log ${LAST_TAG}..HEAD --merges --pretty=format:"%H %s"
- 對於每個合併的 PR，透過 gh pr view <number> --json author --jq '.author.login' 識別 PR 作者
- 與儲存庫擁有者比較（gh repo view --json owner --jq '.owner.login'）
- 若 PR 作者 ≠ 儲存庫擁有者 → 第三方貢獻者
以該語言產生內容：
- 區段標題使用目標語言
- 變更說明以目標語言自然撰寫（非翻譯）
- 日期格式：YYYY-MM-DD（通用）
- 第三方貢獻：在更新日誌條目後附加貢獻者歸屬 (by @username)
插入檔案開頭（保留現有內容）

區段標題翻譯（內建）：

類型	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

更新日誌格式：

## {VERSION} - {YYYY-MM-DD}

### Features
- Description of new feature
- Description of third-party contribution (by @username)

### Fixes
- Description of fix

### Documentation
- Description of docs changes

僅包含有變更的區段。省略空白區段。

第三方歸屬規則：

僅對非儲存庫擁有者的貢獻者添加 (by @username)
使用帶 @ 前綴的 GitHub 使用者名稱
放置在更新日誌條目行的結尾
所有語言一致套用（始終使用 (by @username) 格式，不翻譯）

多語言範例：

英文 (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

中文 (CHANGELOG.zh.md)：

## 1.3.0 - 2026-01-22

### 新功能
- 新增使用者認證模組 (by @contributor1)
- 支援 OAuth2 登入

### 修復
- 修復連線池記憶體洩漏問題

日文 (CHANGELOG.ja.md)：

## 1.3.0 - 2026-01-22

### 新機能
- ユーザー認証モジュールを追加 (by @contributor1)
- OAuth2 ログインをサポート

### 修正
- コネクションプールのメモリリークを修正

步驟 5：依技能/模組分組變更

分析自上次標籤以來的提交，並依受影響的技能/模組分組：

識別每個提交中變更的檔案
依技能/模組分組：
- skills/<skill-name>/* → 歸入該技能
- 根目錄檔案（CLAUDE.md 等）→ 歸入「project」
- 一個提交涉及多個技能 → 拆分為多個群組
對於每個群組，識別需要更新的相關 README

分組範例：

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

步驟 6：分別提交每個技能/模組

對於每個技能/模組群組（依變更順序）：

檢查需要的 README 更新：
- 掃描 README*.md 中提及此技能/模組的部分
- 確認選項/旗標已正確文件化
- 若語法變更，更新使用範例
- 若行為變更，更新功能說明

暫存並提交：

git add skills/<skill-name>/*
git add README.md README.zh.md  # 若為此技能更新
git commit -m "<type>(<skill-name>): <meaningful description>"

提交訊息格式：
- 使用慣例提交格式：<type>(<scope>): <description>
- <type>：feat, fix, refactor, docs, perf 等
- <scope>：技能名稱或「project」
- <description>：清晰、有意義的變更說明

提交範例：

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"

常見的 README 更新需求：

變更類型	需檢查的 README 區段
新增選項/旗標	選項表格、使用範例
重新命名選項	選項表格、使用範例
新功能	功能說明、範例
破壞性變更	遷移說明、棄用警告
內部重構	架構區段（若對使用者公開）

步驟 7：產生更新日誌並更新版本

產生多語言更新日誌（如步驟 4 所述）
更新版本檔案：
- 讀取版本檔案（JSON/TOML/文字）
- 更新版本號碼
- 寫回（保留格式）
建立發布說明檔案：
- 優先使用 CHANGELOG.md 中的新版本區段
- 若無英文/預設更新日誌，則使用第一個偵測到的更新日誌
- 僅提取從 ## {VERSION} - {YYYY-MM-DD} 到下一個 ## 的區段
- 必要時同時匹配純版本和帶標籤前綴的標題，例如 1.2.3 和 v1.2.3
- 將破壞性變更保持在頂部附近；必要時在其他區段前添加簡短重點
- 將說明寫入 UTF-8 暫存檔案，並重複用於註解標籤訊息、GitHub Releases 和 publish_artifact
- 在正常模式下，若找不到說明，則停止而非建立空標籤或 GitHub Release

依檔案類型的版本路徑：

檔案	路徑
package.json	`$.version`
pyproject.toml	`project.version`
Cargo.toml	`package.version`
marketplace.json	`$.metadata.version`
VERSION / version.txt	直接內容

步驟 8：使用者確認

在建立發布提交之前，要求使用者確認：

使用 AskUserQuestion 提出三個問題：

版本升級（單選）：
- 根據步驟 3 分析顯示建議版本
- 選項：建議版本（附標籤）、其他 semver 選項
- 範例：1.2.3 → 1.3.0 (Recommended)、1.2.3 → 1.2.4、1.2.3 → 2.0.0
推送到遠端（單選）：
- 選項：「是，提交後推送」、「否，僅保留本地」
發布 GitHub Release（單選）：
- 僅在 GitHub Release 支援可用時提供此選項
- 當使用者同時選擇推送時，預設為「是，標籤推送後發布」
- 若使用者保留本地發布，則不建立或編輯 GitHub Release

確認前輸出範例：

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

Release notes source: CHANGELOG.md#1.3.0
Ready to create release commit, annotated tag, and GitHub Release.

步驟 9：建立發布提交與註解標籤

在使用者確認後：

暫存版本與更新日誌檔案：

git add <version-file>
git add CHANGELOG*.md

建立發布提交：

git commit -m "chore: release v{VERSION}"

建立註解標籤：
```
git tag -a v{VERSION} -F <release-notes-file>
```
若 .releaserc.yml 設定 tag.sign: true，則使用 git tag -s 搭配相同的說明檔案。

若使用者確認則推送（步驟 8）：

git push origin main
git push origin v{VERSION}

注意：不要添加 Co-Authored-By 行。這是發布提交，而非程式碼貢獻。

步驟 10：發布成品與 GitHub Release

專案成品發布與 GitHub Releases 是分開的輸出：

專案成品：
- 若 release.hooks.publish_artifact 存在，則對每個準備好的目標執行一次
- 傳遞與標籤和 GitHub Release 相同的 {release_notes_file}
- 在乾執行模式中，傳遞 {dry_run}=true 並報告將發布的內容

GitHub Release：

僅在使用者確認遠端發布且 GitHub 支援可用時執行
確保標籤在建立 Release 前已存在於遠端

使用提取的說明建立或更新：

if gh release view v{VERSION} >/dev/null 2>&1; then
  gh release edit v{VERSION} --title "v{VERSION}" --notes-file <release-notes-file>
else
  gh release create v{VERSION} --title "v{VERSION}" --notes-file <release-notes-file> --verify-tag
fi

切勿將多行發布說明內嵌到 shell 命令中

發布後輸出：

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
Tag type: annotated
GitHub Release: published  # or "skipped/local only"
Status: Pushed to origin  # or "Local only - run git push when ready"

回填現有 GitHub Releases

當使用者要求回填歷史版本或傳遞 --backfill-releases 時使用此模式。

不要升級版本、編輯更新日誌或建立發布提交。
依版本順序列出現有標籤並偵測遺失的 Releases：
```
git tag --sort=v:refname
gh release view <tag>
```
對於每個沒有 GitHub Release 的標籤：
- 透過移除設定的標籤前綴來正規化更新日誌查詢，例如 v1.2.3 -> 1.2.3
- 從 CHANGELOG.md 提取匹配的區段；若無則回退到第一個匹配的更新日誌檔案
- 若無匹配的更新日誌區段，則跳過或在發布前詢問
- 使用以下命令建立 Release：
```
gh release create <tag> --title "<tag>" --notes-file <release-notes-file> --verify-tag
```
使用 git cat-file -t <tag> 偵測輕量標籤（commit 表示輕量，tag 表示註解）。
預設不重寫公開的輕量標籤。將現有遠端標籤轉換為註解標籤需要明確的使用者確認，因為這會重寫已發布的參考。

設定檔 (.releaserc.yml)

專案根目錄中的選擇性設定檔，用於覆蓋預設值：

# .releaserc.yml - 選擇性設定

# 版本檔案（若未指定則自動偵測）
version:
  file: package.json
  path: $.version  # JSON 使用 JSONPath，TOML 使用點分隔路徑

# 更新日誌檔案（若未指定則自動偵測）
changelog:
  files:
    - path: CHANGELOG.md
      lang: en
    - path: CHANGELOG.zh.md
      lang: zh
    - path: CHANGELOG.ja.md
      lang: ja

  # 區段對應（慣例提交類型 → 更新日誌區段）
  # 使用 null 跳過更新日誌中的某個類型
  sections:
    feat: Features
    fix: Fixes
    docs: Documentation
    refactor: Refactor
    perf: Performance
    test: Tests
    chore: null

# 提交訊息格式
commit:
  message: "chore: release v{version}"

# 標籤格式
tag:
  prefix: v  # 結果為 v1.0.0
  sign: false

# 發布提交中包含的額外檔案
include:
  - README.md
  - package.json

乾執行模式

當指定 --dry-run 時：

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

使用範例

/release-skills              # 自動偵測版本升級
/release-skills --dry-run    # 僅預覽
/release-skills --minor      # 強制次版本升級
/release-skills --patch      # 強制修訂版本升級
/release-skills --major      # 強制主版本升級（需確認）
/release-skills --backfill-releases  # 為現有標籤建立遺失的 GitHub Releases

使用時機

當使用者要求以下內容時觸發此技能：

"release", "發布", "create release", "new version", "新版本"
"bump version", "update version", "更新版本"
"prepare release"
"release notes", "GitHub Release", "回填 Release"
"push to remote"（有未提交的變更）

重要：若使用者說「just push」或「直接 push」且有未提交的變更，仍應先執行上述所有步驟。

您可能也喜歡

ecommerce-image-workflow

92Kagent-workflows

Reference-product ecommerce image workflow for generating a compact set of product-faithful main, feature, and lifestyle images from real product reference photos. V1 requires uploaded product imagery and intentionally defers brief-only concept generation and platform-specific batch exports.

nexu-io

獲取

github-triage

68Kagent-workflows

Read-only GitHub triage for issues AND PRs. 1 item = 1 background task (category: quick). Analyzes all open items and writes evidence-backed reports to /tmp/{datetime}/. Every claim requires a GitHub permalink as proof. NEVER takes any action on GitHub - no comments, no merges, no closes, no labels. Reports only. Triggers: 'triage', 'triage issues', 'triage PRs', 'github triage'.