AI Plugins 多平台发布助手

本技能是 ai-plugins/common-tools 下的对外分发 skill，唯一真实来源路径为 ai-plugins/common-tools/skills/release-ai-plugins/SKILL.md。

本技能用于自动化处理 ai-plugins 的多插件、多平台发布流程，确保单一主版本一致性和路径稳定性。

使用场景

当遇到以下情况时使用本技能：

需要发布 common-tools 或 dev-skills 插件的新版本
更新 Claude/Cursor 双平台 marketplace 版本号
同步多个 plugin manifest 的版本号
更新发布说明、安装文档、README 链接

核心职责

版本号管理：以主版本驱动双平台与双插件版本同步
更新日志维护：编写符合规范的版本更新说明
清单校验：校验 Cursor/Claude 清单路径与字段
文档同步：确保安装文档中的路径、命令、链接均指向 ai-plugins

主版本策略

采用单一总版本（Single Source of Truth）：

主版本源：.claude-plugin/marketplace.json 的 metadata.version
同步目标：
- .cursor-plugin/marketplace.json 的 metadata.version
- 两个插件在 Claude/Cursor 的 plugin.json 中 version

Skills 文档的 metadata.version 字段

Skill 文档版本号保持独立演进：仅在该 Skill 内容有变更时更新，不强制随插件主版本同步。

扫描范围：

ai-plugins/common-tools/skills/**/SKILL.md
ai-plugins/dev-skills/skills/**/SKILL.md

主版本号格式

遵循语义化版本规范（Semantic Versioning）：

MAJOR.MINOR.PATCH（例如：2.12.1）
MAJOR：不兼容的 API 修改
MINOR：向下兼容的功能性新增
PATCH：向下兼容的问题修正

README 与文档同步规则

发布时至少校验以下文档路径与命令：

ai-plugins/docs/README.md
ai-plugins/docs/use-vercel-skills-install.md
.claude-plugin/README.md
.cursor-plugin/README.md
根 README.md

所有安装命令必须使用 ai-plugins/... 路径，不允许出现 claude-code-marketplace/... 旧路径。

更新日志文件

每次版本更新的内容必须记录在以下文件中：

ai-plugins/common-tools/CHANGELOG.md
ai-plugins/dev-skills/CHANGELOG.md（如不存在则创建）

更新日志格式

遵循 Keep a Changelog 规范：

## [版本号] - YYYY-MM-DD

### Added

- 新增的功能

### Changed

- 变更的功能

### Deprecated

- 即将废弃的功能

### Removed

- 已移除的功能

### Fixed

- 修复的问题

### Security

- 安全相关的修复

更新日志排版要求

写 CHANGELOG.md 时，优先保证可读性，再保证信息完整。不要把 4 到 6 个变化点硬堆进一条超长 bullet。

必须遵守

先写版本节与分类节，再写 bullet；不要先堆内容后补结构。
一类变化尽量拆成多条 flat bullets，每条只承载一个独立信息块。
技能或插件名放在 bullet 开头，版本变化紧跟其后，便于扫读。
文件名、命令、版本号、字段名统一用反引号包裹。
“版本同步”与“功能变化”分开写，不能混进同一长句。
major 级变更优先按“行为变化 / 配置变化 / 风险边界变化 / 版本同步”拆开。

明确禁止

禁止单条 bullet 同时塞入多个分号串联的大段说明。
禁止把多个文件、多个原因、多个效果揉成一个 3 到 5 行的大段落。
禁止为了“信息完整”牺牲扫读体验。
禁止生成视觉上发紧、读者必须逐字解析的 changelog。

反例

- **init-release-base-relizy-and-bumpp**（`metadata.version` `1.1.1` -> `2.0.0`，重大调整）：将根包 changelog 默认生成链路从 `conventional-changelog` 收口到 `changelogen`，并同步重写根包 `bumpp` 模板的执行方式与发版预检边界，`templates/bump.config.ts` 改为 `execute` 函数并传 `newVersion`，`templates/release.yaml` 保留既有注释风格，只最小补充 `set +e` / `set -e`，预检也从旧 angular preset 冲突收缩为遗留根包发版工具残留……

上面的反例信息并没有错，但排版是错的。以后生成 changelog 时，必须主动把这种长句拆开。

升级流程

执行版本升级时，按顺序执行：

确定主版本号
- 根据变更类型确定主版本增量（MAJOR/MINOR/PATCH）
同步双平台 marketplace
- 更新 .claude-plugin/marketplace.json 的 metadata.version
- 更新 .cursor-plugin/marketplace.json 的 metadata.version
同步双插件 manifest
- 更新 ai-plugins/common-tools 的 Claude/Cursor plugin.json 版本
- 更新 ai-plugins/dev-skills 的 Claude/Cursor plugin.json 版本
按需更新 Skills 版本
- 仅更新变更过的 SKILL.md 的 metadata.version
更新文档与 changelog
- 修正安装命令路径与插件列表
- 在对应 CHANGELOG.md 顶部追加新版本条目
- 先把 changelog 草稿整理成易扫读的 Markdown 结构，再填充细节
- 对 major 变更，至少检查一次是否仍存在“单条 bullet 过长”的问题
一致性校验
- 校验 marketplace 与 plugin 版本是否一致
- 校验 source/pluginRoot 指向是否存在
- 校验文档命令路径是否只使用 ai-plugins
- 校验 CHANGELOG.md 是否由短句 bullet 组成，而不是一整段拥挤长句
提交发布改动
- 推荐提交信息：chore(plugin): release version X.Y.Z

注意事项

主版本一致性：双平台 marketplace + 双插件 manifest 必须一致。
平台规范分离：Cursor 与 Claude 字段可能不同，按各自规范维护。
旧路径禁用：发布前必须确认无 claude-code-marketplace 路径残留。
Skills 独立版本：Skill 的 metadata.version 只在该 Skill 变更时更新。
更新日志优先可读性：如果 changelog 一眼看上去像“压成一团的说明书”，说明写法失败，需要重排。

release-ai-plugins