release-skills

发布技能

支持任意项目类型的通用发布工作流，支持多语言变更日志。

快速开始

只需运行 /release-skills——自动检测项目配置。

支持的项目

项目类型	版本文件	自动检测
Node.js	package.json	✓
Python	pyproject.toml	✓
Rust	Cargo.toml	✓
Claude 插件	marketplace.json	✓
通用	VERSION / version.txt	✓

选项

标记	说明
--dry-run	预览变更，不执行操作
--major	强制提升主版本号
--minor	强制提升次版本号
--patch	强制提升修订版本号

工作流

步骤 1：检测项目配置

1. 检查 .releaserc.yml（可选的配置覆盖文件）
2. 扫描并自动检测版本文件（按优先级排序）：
   • package.json（Node.js）
   • pyproject.toml（Python）
   • Cargo.toml（Rust）
   • marketplace.json 或 .claude-plugin/marketplace.json（Claude 插件）
   • VERSION 或 version.txt（通用）
3. 使用 glob 模式扫描变更日志文件：
   • CHANGELOG*.md
   • HISTORY*.md
   • CHANGES*.md
4. 根据文件名后缀识别每个变更日志的语言
5. 显示检测到的配置

语言检测规则：

文件名模式	语言
CHANGELOG.md（无后缀）	en（默认）
CHANGELOG.zh.md / CHANGELOG_CN.md / CHANGELOG.zh-CN.md	zh
CHANGELOG.ja.md / CHANGELOG_JP.md	ja
CHANGELOG.ko.md / CHANGELOG_KR.md	ko
CHANGELOG.de.md / CHANGELOG_DE.md	de
CHANGELOG.fr.md / CHANGELOG_FR.md	fr
CHANGELOG.es.md / CHANGELOG_ES.md	es
CHANGELOG.{lang}.md	对应的语言代码

输出示例：

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：确定版本升级幅度

规则（按优先级排序）：

1. 用户标记 --major/--minor/--patch → 使用指定选项
2. 检测到 BREAKING CHANGE → 提升主版本号（1.x.x → 2.0.0）
3. 存在 feat: 提交 → 提升次版本号（1.2.x → 1.3.0）
4. 其他情况 → 提升修订版本号（1.2.3 → 1.2.4）

显示版本变更：1.2.3 → 1.3.0

Step 4：生成多语言变更日志

针对每个检测到的变更日志文件：

1. 根据文件名后缀识别语言
2. 检测第三方贡献者：
   • 检查合并提交：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 作者 ≠ 仓库所有者，则视为第三方贡献者
3. 以对应语言生成内容：
   • 使用目标语言编写章节标题
   • 使用目标语言自然地撰写变更描述（而非翻译）
   • 日期格式：YYYY-MM-DD（通用格式）
   • 第三方贡献：在变更日志条目后附上贡献者署名 (by @username)
4. 插入文件开头（保留现有内容）

章节标题翻译（内置）：

Type	en	zh	ja	ko	de	fr	es
feat	功能	新功能	新機能	새로운 기능	Funktionen	Fonctionnalités	Características
fix	修复	修复	修正	수정	Fehlerbehebungen	Corrections	Correcciones
docs	文档	文档	ドキュメント	문서	Dokumentation	Documentation	Documentación
refactor	重构	重构	リファクタリング	리팩토링	Refactoring	Refactorisation	Refactorización
perf	性能优化	性能优化	パフォーマンス	성능	Leistung	Performance	Rendimiento
breaking	破坏性变更	破坏性变更	破壊的変更	주요 변경사항	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 ログインをサポート

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

Step 5：按技能/模块分组变更

分析自上一个标签以来的提交，并按受影响的技能/模块分组：

1. 识别每个提交中变更的文件
2. 按技能/模块分组：
   • skills/<skill-name>/* → 归入对应技能
   • 根目录文件（CLAUDE.md 等）→ 归入“项目”
   • 一个提交涉及多个技能 → 拆分为多个组
3. 针对每个组，确定需要更新的相关 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

Step 6：分别提交每个技能/模块的变更

按变更顺序处理每个技能/模块组：

1. 检查是否需要更新 README：

   • 扫描 README*.md，查找对此技能/模块的提及
   • 核实选项/标志的文档是否正确
   • 如果语法变更，更新用法示例
   • 如果行为变更，更新功能描述

2. 暂存并提交：

   git add skills/<skill-name>/*
   git add README.md README.zh.md  # If updated for this skill
   git commit -m "<type>(<skill-name>): <meaningful description>"
   

3. 提交消息格式：

   • 使用约定式提交格式：<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：生成变更日志并更新版本

1. 生成多语言变更日志（如步骤 4 所述）
2. 更新版本文件：
   • 读取版本文件（JSON/TOML/文本）
   • 更新版本号
   • 写回文件（保留格式）

不同文件类型对应的版本路径：

文件	路径
package.json	$.version
pyproject.toml	project.version
Cargo.toml	package.version
marketplace.json	$.metadata.version
VERSION / version.txt	直接内容

步骤 8：用户确认

创建发布提交前，请用户确认：

使用 AskUserQuestion 提出两个问题：

1. 版本升级（单选）：

   • 显示基于步骤 3 分析得出的建议版本
   • 选项：建议版本（带标签）、其他 semver 选项
   • 示例：1.2.3 → 1.3.0 (Recommended)、1.2.3 → 1.2.4、1.2.3 → 2.0.0

2. 推送到远程（单选）：

   • 选项："Yes, push after commit"、"No, keep local only"

确认前的输出示例：

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

Ready to create release commit and tag.

步骤 9：创建发布提交和标签

用户确认后：

1. 暂存版本和变更日志文件：

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

2. 创建发布提交：

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

3. 创建标签：

   git tag v{VERSION}
   

4. 根据用户确认推送（步骤 8）：

   git push origin main
   git push origin v{VERSION}
   

注意：不要添加 Co-Authored-By 行。这是发布提交，而非代码贡献。

发布后的输出：

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
Status: Pushed to origin  # or "Local only - run git push when ready"

配置（.releaserc.yml）

可在项目根目录中添加可选配置文件以覆盖默认值：

# .releaserc.yml - Optional configuration

# Version file (auto-detected if not specified)
version:
  file: package.json
  path: $.version  # JSONPath for JSON, dotted path for TOML

# Changelog files (auto-detected if not specified)
changelog:
  files:
    - path: CHANGELOG.md
      lang: en
    - path: CHANGELOG.zh.md
      lang: zh
    - path: CHANGELOG.ja.md
      lang: ja

  # Section mapping (conventional commit type → changelog section)
  # Use null to skip a type in changelog
  sections:
    feat: Features
    fix: Fixes
    docs: Documentation
    refactor: Refactor
    perf: Performance
    test: Tests
    chore: null

# Commit message format
commit:
  message: "chore: release v{version}"

# Tag format
tag:
  prefix: v  # Results in v1.0.0
  sign: false

# Additional files to include in release commit
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              # Auto-detect version bump
/release-skills --dry-run    # Preview only
/release-skills --minor      # Force minor bump
/release-skills --patch      # Force patch bump
/release-skills --major      # Force major bump (with confirmation)

适用场景

用户提出以下请求时触发此技能：

• “release”、“发布”、“create release”、“new version”、“新版本”
• “bump version”、“update version”、“更新版本”
• “prepare release”
• 存在未提交更改时请求“push to remote”

重要：如果用户在存在未提交更改时说“just push”或“直接 push”，仍需先遵循上述所有步骤。