Cutting A Release
TriliumNext/Trilium
A skill your agent uses when cutting, preparing, or debugging a Trilium release — bumping the monorepo version, tagging, or diagnosing a failed "Release" workflow run.
本技能应在 GitHub 项目发布新版本时使用，覆盖版本号管理、CHANGELOG 同步、Release Notes 撰写、tag 创建、CI 构建监控、发布验证和历史清理全流程。适用于桌面应用、CLI 工具、Web 应用、库/SDK 等任何基于 GitHub 的软件项目。当用户提到"发布"、"release"、"打 tag"、"新版本"、"更新版本号"、"写 release…
Install Release Workflow
$ npx skills add cat-xierluo/legal-skills --skill release-workflow -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install cat-xierluo/legal-skills release-workflow --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/cat-xierluo/legal-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/release-workflow .claude/skills/release-workflow && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "release-workflow" agent skill from https://github.com/cat-xierluo/legal-skills/tree/main/skills/release-workflow into .claude/skills/release-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "release-workflow", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/cat-xierluo/legal-skills/tree/main/skills/release-workflowType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add cat-xierluo/legal-skills --skill release-workflow -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install cat-xierluo/legal-skills release-workflow --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cat-xierluo/legal-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/release-workflow .agents/skills/release-workflow && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "release-workflow" agent skill from https://github.com/cat-xierluo/legal-skills/tree/main/skills/release-workflow into .agents/skills/release-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "release-workflow", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add cat-xierluo/legal-skills --skill release-workflow -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install cat-xierluo/legal-skills release-workflow --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cat-xierluo/legal-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/release-workflow .cursor/skills/release-workflow && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "release-workflow" agent skill from https://github.com/cat-xierluo/legal-skills/tree/main/skills/release-workflow into .cursor/skills/release-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "release-workflow", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/cat-xierluo/legal-skills.git --path skills/release-workflow--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add cat-xierluo/legal-skills --skill release-workflow -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install cat-xierluo/legal-skills release-workflow --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cat-xierluo/legal-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/release-workflow .gemini/skills/release-workflow && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "release-workflow" agent skill from https://github.com/cat-xierluo/legal-skills/tree/main/skills/release-workflow into .gemini/skills/release-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "release-workflow", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install cat-xierluo/legal-skills release-workflowInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add cat-xierluo/legal-skills --skill release-workflow -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/cat-xierluo/legal-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/release-workflow .github/skills/release-workflow && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "release-workflow" agent skill from https://github.com/cat-xierluo/legal-skills/tree/main/skills/release-workflow into .github/skills/release-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "release-workflow", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add cat-xierluo/legal-skills --skill release-workflow -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install cat-xierluo/legal-skills release-workflow --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cat-xierluo/legal-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/release-workflow .opencode/skills/release-workflow && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "release-workflow" agent skill from https://github.com/cat-xierluo/legal-skills/tree/main/skills/release-workflow into .opencode/skills/release-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "release-workflow", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
release-workflow- GitHub stars
- 713
- Token cost
- ~3.5k tokens
- SKILL.md length
- 1,135 words
- Files
- 23 (incl. scripts, references)
- Skills in repo
- 62
- Repo updated
- First seen
- Licence
- MIT
At a glance
本技能应在 GitHub 项目发布新版本时使用，覆盖版本号管理、CHANGELOG 同步、Release Notes 撰写、tag 创建、CI 构建监控、发布验证和历史清理全流程。适用于桌面应用、CLI 工具、Web 应用、库/SDK 等任何基于 GitHub 的软件项目。当用户提到"发布"、"release"、"打 tag"、"新版本"、"更新版本号"、"写 release…
- Works in 5 steps: 这是给真实用户装的，还是只给自己看 artifact？ → CHANGELOG 已经有结构化的本版本条目（不是空、不是单行 typo）？ → 距上次 tag ≥ 24 小时？ → …
- Tasks that involve Changelog and release notes
- SKILL.md covers 适用场景, 项目配置, 发布前检查 and ⚠️ Release ≠ 测试 — 强制约束, plus 6 more sections
- Runs Python and Shell scripts from its folder; calls git, gh and npm; needs GITHUB_TOKEN
What it does
Release Workflow is an agent skill from cat-xierluo/legal-skills. 本技能应在 GitHub 项目发布新版本时使用，覆盖版本号管理、CHANGELOG 同步、Release Notes 撰写、tag 创建、CI 构建监控、发布验证和历史清理全流程。适用于桌面应用、CLI 工具、Web 应用、库/SDK 等任何基于 GitHub 的软件项目。当用户提到"发布"、"release"、"打 tag"、"新版本"、"更新版本号"、"写 release notes"、"发布失败了"、"CI 挂了"、"Actions 配额告急"、"短时间内多次发版"、"monorepo"、"批量打包"、"多 skill 发布"、"skill zip"、"专家套件 zip"时触发。也用于拒绝把 release 当作 CI 验证机制（"打 tag 看一下"）的反模式场景。不要用于非 GitHub 项目（如纯 GitLab / Gitea 项目）或无需 CI 的手动发布场景。
Its SKILL.md is about 3.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 25 other files, including scripts and reference files (for example `CHANGELOG.md`, `config/projects.example.yaml` and `config/projects.yaml`).
It sits in Development, covering Changelog and release notes and Monorepo tooling. It works with GitHub, GitLab and macOS. The licence is MIT.
When your agent uses it
- Tasks that involve Changelog and release notes
- Tasks that involve Monorepo tooling
Example prompts
- “release”
- “写 release notes”
- “Actions 配额告急”
- “/release-workflow”
Requirements
- Python 3
- A Bash shell
Workflow steps
5 steps, taken from the first numbered list in SKILL.md.
- 这是给真实用户装的，还是只给自己看 artifact？
- CHANGELOG 已经有结构化的本版本条目（不是空、不是单行 typo）？
- 距上次 tag ≥ 24 小时？
- 本次累计有 ≥ 1 个实质修复 / 特性 / 改动（纯文档 / typo / 单行 README 修改不算）？
- 如果上述任一不满足：能合并到下次发版吗？
What it can do on your machine
Read from SKILL.md and the folder at commit c077fcc. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 9 files in scripts/ (Python and Shell, from the files we listed), which the agent can run.
Shell commands in SKILL.md call:
gitghnpmbash
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, gh and npm, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
GITHUB_TOKEN
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Release Workflow loads about 3.5k tokens when it runs, and up to ~15k if it reads all its reference files. Until then it costs about 103 tokens; SKILL.md has 1,135 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.
SKILL.md
The full file from cat-xierluo/legal-skills at commit c077fcc, republished under its MIT licence (© cat-xierluo). 1,135 words, ~3,499 tokens.
Download SKILL.mdSave it as
.claude/skills/release-workflow/SKILL.md (or your agent's skills folder). This skill also uses 22 other files; get the full folder from GitHub.- name
- release-workflow
- description
- 本技能应在 GitHub 项目发布新版本时使用，覆盖版本号管理、CHANGELOG 同步、Release Notes 撰写、tag 创建、CI 构建监控、发布验证和历史清理全流程。适用于桌面应用、CLI 工具、Web 应用、库/SDK 等任何基于 GitHub 的软件项目。当用户提到"发布"、"release"、"打 tag"、"新版本"、"更新版本号"、"写 release notes"、"发布失败了"、"CI 挂了"、"Actions 配额告急"、"短时间内多次发版"、"monorepo"、"批量打包"、"多 skill 发布"、"skill zip"、"专家套件 zip"时触发。也用于拒绝把 release 当作 CI 验证机制（"打 tag 看一下"）的反模式场景。不要用于非 GitHub 项目（如纯 GitLab / Gitea 项目）或无需 CI 的手动发布场景。
- version
- 1.6.2
- license
- MIT License - 详见 LICENSE.txt
Release Workflow
软件项目的全流程发布工作流。适用于 GitHub 上的任何类型项目。
适用场景
GitHub 项目的完整发布周期：从版本号确定到 CI 构建验证。CI 故障排查（references/ci-troubleshooting.md）和特定项目类型指南（references/ 下各文档）作为发布流程的补充参考。
与 git-workflow 的职责边界：本技能只负责发版流程内的 CI 构建监控（第 4 步）与发布成本约束（配额红灯）。日常 Actions 配额治理——CI 分钟耗尽停挂止血、workflow 停挂/恢复、workflow_dispatch 化、仓级总闸——由 git-workflow §11 负责。发版中出现 CI 故障：构建产物/签名/发布链路问题读本技能；账号级配额治理问题转 git-workflow。
项目配置
config/projects.yaml 集中管理各项目的发布配置（仓库、平台、自动更新、排除产物等）。发布时先读取对应项目配置，按配置决定构建矩阵和预期产物。模板见 config/projects.example.yaml。
发布前检查
| 检查项 | 说明 |
|---|---|
| 工作区干净 | git status 无未提交变更 |
| 版本号一致 | 所有版本号文件（package.json / Cargo.toml / pyproject.toml 等）与 CHANGELOG.md 最新条目一致 |
| CHANGELOG 已更新 | 包含目标版本的结构化条目 |
| CI 工作流存在 | .github/workflows/ 中有 release 相关工作流且 tag 触发配置正确 |
| 本地测试门禁 | npm test（或项目对应单测命令）整体通过。单条失败先重跑确认是否偶发再定性：偶发 flaky（非本次改动引入的回归）修测试或单独跟进，不要因此阻塞发布；但若全量多次复现、指向真实回归，必须先修复再发版 |
任一条件不满足，先修复再继续。
⚠️ Release ≠ 测试 — 强制约束
打 tag / 创建 GitHub Release 是把版本号给真实用户，不是 CI 验证机制。把 release workflow 当作"看 CI 跑没跑通"或"我下载个 artifact 自己测一下"是反模式，必须禁止。
为什么是绝对规则
- Actions 配额是有限共享资源。单次跨平台 release（macOS × N + Windows + Linux）通常消耗 300-600 配额分钟，macOS runner 是 10× 费率，贡献最大。
- 错把 release 当测试的隐性成本：
- GitHub Release 一旦创建（即使是 draft）就被计入资产历史，污染 release feed
- tag 推送后 commit 被人看到会误以为已发布
- 自动更新用户可能在升级检查时看到不稳定的版本
- 配额快速耗尽，真正紧急的 hotfix 反而跑不动 CI
- 过去能这么干不代表现在该这么干。GitHub 免费配额调整、macOS runner 涨价都发生过，使用模式必须随成本变化更新。
禁止的反模式
| 反模式 | 表现 | 为什么错 |
|---|---|---|
| 把 tag 当 smoke test | "我改了一行，打个 tag 看看 CI 跑不跑得通" | 一次 release 吃掉 300+ 配额分钟，5 次测试 = 一月配额清零 |
| 用 release 验证构建产物 | "我想看 .dmg 长什么样，必须跑 release" | 应该用专门的 preview / draft build workflow（见下） |
| 同一天 / 24h 内发多个 patch | v0.3.16 / 17 / 18 一天内连发，各是同一个 bug 的连续小修 | 全部攒到下次一起发，成本立省 60%+ |
| draft release 当"先跑一次试试" | "我先 draft release 看 artifact 行不行" | draft 一样跑完整 CI，一样消耗配额，一样污染 release 历史 |
| 单平台 dry-run 验构建 | "先跑 Linux dry-run 看看，不发全平台" | dry-run 一样消耗 CI 时间，开了口子就停不下来；改走 preview workflow |
| 小改动发 patch | "我改了 typo / 改了一行文档，必须 vX.Y.Z" | 纯 typo / 文档小改 / 单文件改动不构成发版理由，合并到下个有实质内容的版本 |
| "已经打 tag 了，跑都跑了" | "v0.3.22 tag 已经推上去了，CI 反正也在跑" | "已经做了"不是继续做的理由；记录这次浪费并阻止下次重复 |
正确做法
A. 想验证 CI 跑不跑得通 / 看构建产物长什么样？
- 用
pull_request触发的 preview workflow（可只跑 ubuntu / 单一平台，几十分钟完成） - 或在 main 上用
workflow_dispatch手动触发 dry build，不触发 release workflow - 这两种都不消耗 macOS 高倍率配额，artifact 只对自己可见
B. 真的有用户能拿到的修复要发？
- 等攒到 3-5 个实质修复（bug fix / feature / 性能 / 兼容性改动）
- 一次性打 tag 发版，只发一次
- CHANGELOG 必须有结构化条目，不能空
- 距离上次 tag 至少 24 小时（防止把单个 hotfix 拆成多个 patch）
打 tag 前强制自检（AI 不得跳过）
打 tag 之前，必须回答下面 5 个问题。AI 代理被请求发布新版本时，必须主动逐条打印结果让用户确认，禁止直接进入打 tag 流程。
- 这是给真实用户装的，还是只给自己看 artifact？
- CHANGELOG 已经有结构化的本版本条目（不是空、不是单行 typo）？
- 距上次 tag ≥ 24 小时？
- 本次累计有 ≥ 1 个实质修复 / 特性 / 改动（纯文档 / typo / 单行 README 修改不算）？
- 如果上述任一不满足：能合并到下次发版吗？
任一答"否"或"不知道"：不要打 tag，改走 preview workflow 或合并到下次。
AI 代理实操规则：用户说「发布新版本」「打 tag」「release」时，AI 必须先在响应中显式列出 5 问的答案，等用户确认后再继续。这是硬约束，不允许跳过——v0.4.0 发布时 AI 跳过此步骤导致 3 次重打 tag 才修好，是真实教训。
借口反驳表
| 借口 | 现实 |
|---|---|
| "我就看一眼，tag 一下马上回滚" | tag 推送已经触发了完整 CI，回滚 tag 不能退款 Actions 分钟 |
| "用户催着要" | 用户不知道你的 Actions 配额，告诉 ta 合并到明天的成本和时间，让 ta 选 |
| "反正之前都这么干" | 之前能用不等于现在合理，这正是 91% 配额的直接成因 |
| "只有 release workflow 跑完整矩阵" | 加一个 preview workflow（成本是 release 的 10-20%），不要用 release 凑合 |
| "draft release 不算正式发布" | draft 一样跑完整 CI、一样消耗配额、一样污染 release 历史 |
| "小改动发 patch 很常见" | 纯 typo / 文档 / 单行不构成发版理由，合并到下个有实质内容的版本 |
| "我已经打 tag 了，跑都跑了" | "已经做了"不是继续做的理由；记录这次浪费，阻止下次重复 |
| "单平台先 dry-run 一下" | dry-run 一样消耗 CI 时间，开了口子就停不下来；改走 preview workflow |
| "这次不一样，这次真的需要发" | SemVer 的 patch 版本本来就允许累积；下次发版不是更优解吗 |
红灯（看到任一就停）
- 同一工作日内想发第二次 tag
- 距上次 tag < 24 小时
- CHANGELOG 没有本版本的结构化条目就想发
- 想用 "draft release" 当测试
- 想用
workflow_dispatch触发 release workflow 当测试（应该触发独立的 preview workflow） - 本次只有 typo / 文档 / 单行修改
- macOS 10× 配额当月累计用量已 > 70%
以上任一出现：删掉 tag（如已打），改走 preview workflow 或合并到下次。
🔥 修复 hotfix 与 CI retry 边界（关键）
patch 版本（X.Y.Z+1）可以是 新功能累积，也可以是 hotfix 单一修复。区分清楚才能避免「把 release 当测试」反模式。
何时属于「hotfix 真实修复」（可以重打 tag）
- 第一次 release 后用户实际收到 broken build（自动更新坏 / 安装失败 / 启动崩溃）
- CI 日志明确指向代码层 bug（编译错、依赖配置错、产物链断裂）
- 每次重打 tag 都有可验证的 commit 推进（修一行、改一个配置、新增测试）
判定信号：gh run view --log-failed 输出包含具体 error line（不是单纯的 Timeout / Resource exhausted 这种 transient 错误）。
何时属于「把 release 当测试」（禁止重打 tag）
- 单纯想看 CI 跑没跑通、看 artifact 长什么样
- 上一次 build 失败但没看失败原因就直接重打
- 第三次以上重打同一个版本号（按成本曲线，超过 3 次几乎都在反复折腾 transient）
transient vs 真实 bug 的快速判定
build job 失败：
- 输出含 E0599 / Cargo compile error / 链接错误 → 真实代码 bug，修代码再重打
- 输出含 "Timeout" / "Resource exceeded" / "Killed" → transient，可直接重试
publish job 失败：
- 输出 "Missing signatures" + 产物清单缺 sig → 检查 includeUpdaterJson + bundle.targets（详见 tauri-release.md 红线 8）
- 输出 "Signature not found for the updater JSON. Skipping upload..." → tauri-action 跳过整批 updater，检查 build 产物目录
- 输出 "Unable to download" / "rate limit" → transient
本地单测（vitest / jest）失败，发布前门禁：
- 单条 "Timed out waiting for condition" 超时失败 → 大概率 flaky（轮询式 waitUntil + 动态 import 的异步链在测试环境下偶发跑不完），先重跑该文件确认；连跑仍偶发则修测试（轮询预算给足），不属于本次改动引入的回归，不阻塞发布
- 多条/全量复现、或错误指向具体代码行为 → 真实回归，先修代码再发版最佳实践：先 gh release view <tag> --json assets 看产物清单，再决定修代码还是重打 tag。
修复 hotfix 的标准动作序列
- 删旧 tag + draft release（如已创建）：
git push origin :refs/tags/vX.Y.Z+gh release delete vX.Y.Z --yes - 在 main 上 commit 修复（必须包括版本号同步——commit history 必须含 4 处版本号文件：package.json / Cargo.toml / tauri.conf.json / pyproject.toml 等）
- 重打 tag 指向修复 commit
- 推 tag 触发 CI
- 重打 tag 总次数上限 3 次（含初始 publish）。超过说明根因判断有误，应停下来重新调查。
模式 B:monorepo 多组件批量发布
适用:一个仓库下有 N 个独立可发布的子项目(skill 集、CLI 工具集、npm 包集等),希望一次 tag 同时发布所有子项目的 zip；也支持由仓库内符号链接定义、Release 时展开为真实目录的专家套件 zip。
前置:对应项目需在 config/projects.yaml 有 type: monorepo-skills 条目,并配套 scripts/build-zips.sh + scripts/release-monorepo.sh。启用专家套件时，再配置 expert_suites_root 并使用 validate-expert-suites.py + build-suite-zips.sh；完整 SOP 见 references/monorepo-release.md。
与模式 A 的关键差异(相对单仓库单应用):
| 维度 | 模式 A(单应用) | 模式 B(monorepo) |
|---|---|---|
| tag 频率 | 每应用 1 tag | 每发布轮次 1 tag(常用 CalVer) |
| zip 命名 | <App>-<ver>.<ext> | <skill>-<semver>.zip；套件为 suite-<id>-<semver>.zip |
| Release Notes | 单应用 changelog | N 个 skill changelog 合并 |
| 验证 | 平台矩阵(win/mac/linux) | 子项目数量清单 + 关键项抽查 |
| 回写 README | 不适用 | 是(把 latest URL 写进表格) |
核心流程(详见 references/monorepo-release.md):
- 读
projects.yaml的<project-key>条目,获取skills_root、expert_suites_root、output_dir、exclude_globs - 跑
build-zips.sh <tag>生成单 Skill ZIP；存在专家套件时，再跑静态校验与build-suite-zips.sh <tag> - 打 tag、推 tag
- GitHub Actions(release.yml)自动:上传单 Skill ZIP + 专家套件 ZIP + 生成 Release Notes(含「专家套件」清单节) + 内嵌 README 回写(checkout main → 调
scripts/update-readme.py同步根 README 与expert-suites/*/README.md的下载链接 → commit + push) - 验证 release 页 assets 数量 = 单 Skill ZIP 数 + 套件 ZIP 数;Release Notes 里的 skill 总数取自产物目录但排除
suite-*前缀,套件数用{suites}单独渲染
README 回写不依赖
on: release事件——GITHUB_TOKEN 创建的 Release 受 GitHub 防递归机制限制,不会级联触发其他 workflow(实际从未生效过)。update-readme.yml以workflow_run(Release workflow 成功后)+workflow_dispatch作兜底,与 release.yml 调用同一份scripts/update-readme.py,不存在第二份逻辑;workflow_run 触发时 checkout 显式ref: main(默认会 checkout 到 tag SHA 的 detached HEAD,push 失败)。
下载链接检查必须匹配实际下载列 href 的完整资产路径，不能用正文里的正确 URL 掩盖错误链接。源码检查不联网证明资产存在；保留的公开链接应先对照真实 Release 资产核实，不要用 align-suite-links.py 把源码 README 改成尚不存在的新版本下载。
- 严格默认：
validate-expert-suites.py不带模式仍要求当前版本下载入口；--mode release为相同严格检查。 - 源码/prebuild：显式
--mode source允许真实旧版入口，但成员作用列须准确写；源码 v<当前版本> 待发布；尚无公开成员包时，下载列写尚无公开下载。已有整套旧包使用独立行> 整套源码 v<当前版本> 待发布；首次未发布套件使用> 整套源码 v<当前版本> 待首次发布（尚无公开下载），不得另加未来 ZIP 占位 URL。成员、许可证、Git 跟踪、name、版本和链接边界检查不降级。 - Preview：
SUITE_BUILD_MODE=preview bash scripts/build-suite-zips.sh pr-<编号>，展开同一源码快照并保留真实公开链接/待发布说明；不把 PR 预览说成 GitHub Release 下载。 - 本地 Release staging：先生成当前成员 ZIP，再以默认
release模式构建套件。staging renderer 核对成员 ZIP 的完整文件集合及逐文件字节、拒绝 symlink/重复文件，随后只在临时目录重写本次 tag 和实际成员版本。源码工作树及.gitattributes必须与SOURCE_REF一致；失败不覆盖上一批套件包。此本地构建不执行上传或发布，正式发布仍按原授权门禁。
专家套件成员以 expert-suites/<id>/skills/* 的相对符号链接为唯一构建清单，不增加 suite.yaml。构建器先校验链接未逃逸、README 成员表一致、成员许可证齐全，再从指定 Git tree 导出真实 Skill 目录；Release ZIP 中不得保留符号链接。
README 结构性同步（发版必查，回写覆盖不了的部分）：自动回写只处理已有表行的链接与版本列；加行、分节归属、描述是结构性维护，必须在发版环节人工/AI 完成——
- 跑
scripts/check-readme-coverage.py：Release 每个资产在 README 技能表必须有行、有下载链接（独立仓库行豁免）；缺行说明新技能/迁移技能没同步 README，先补行再发版或发版后立即补 - 分节归属自查：行的分节与技能性质一致——通用工具类（报销整理、签到、复盘等）不进「法律专业应用」节；分类标签（第 2 列）与许可证、SKILL.md description 相互印证
- 描述与
skills/<name>/SKILL.mdfrontmatter 一致，不得凭空编写
不要用于:单应用桌面/CLI/Web 项目(用模式 A 上文 7 步流程)、跨仓库分发(用 subtree-publish skill)。
Show full SKILL.md (332 more words)Show less
所需权限与副作用
- 本地 Preview 只读取当前 Git tree，并在仓库
pack-skills/写入 ZIP；不会创建 tag、联网、安装依赖或修改 README。 - 正式发布会读取 Git 状态、执行
git fetch、创建 annotated tag、把已核验的不可变 tag OID 推送到origin，并通过gh读取 Actions 与 Release 状态。执行前必须完成 Release 五问并设置RELEASE_CONFIRMED=1。 - 正式发布只允许从干净、非 detached、且 HEAD 与
origin/main一致的 main 工作树执行；已有同名本地或远端 tag、身份缺失、CI 失败或资产数不一致均 fail-closed。 RELEASE_GIT_NAME与RELEASE_GIT_EMAIL可显式绑定 tagger 身份；未设置时读取当前 Git 身份，但字段为空会阻断。- 下载链接回写由权限仅为
contents: write的update-readme.yml在 release workflow 成功后执行；本地发布脚本不提交或推送分支。 - 脚本仅访问 GitHub 当前仓库及其 Actions/Release API，不读取云服务凭证内容；Token 由 GitHub Actions 或
gh自身管理，不写入产物和日志。
发布流程
第 1 步：确定版本号
从用户处获取或从 CHANGELOG.md 读取目标版本号。
统一所有版本号文件（按项目类型选取）：
- Node.js 项目：
package.json→version - Rust 项目：
Cargo.toml→version - Python 项目：
pyproject.toml→version - 桌面应用：对应配置文件（如 Tauri 的
tauri.conf.json） - CHANGELOG.md → 最新
## [x.y.z]条目
版本号规则（SemVer）：
| 类型 | 示例 | 适用场景 |
|---|---|---|
| PATCH | 0.3.7 → 0.3.8 | Bug 修复、小改进 |
| MINOR | 0.3.x → 0.4.0 | 新功能、向后兼容 |
| MAJOR | 0.x → 1.0.0 | 重大架构变更、破坏性改动 |
第 2 步：生成 Release Notes
信息来源有两个，必须综合使用：
来源 1 — CHANGELOG.md：结构化的变更分类（Added / Changed / Fixed 等）
来源 2 — git log：两个 tag 之间的 commit 历史，补充上下文和细节
# 获取上一个 tag
PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
# 查看 commit 历史
git log ${PREV_TAG}..HEAD --oneline
# 查看详细变更（含 PR 链接）
git log ${PREV_TAG}..HEAD --format="- %s (%h)"来源 3 — PR 作者信息（外部贡献者识别）：
# 本版本区间合入的 PR 与作者（识别需要致谢的外部贡献者）
gh pr list --state merged --limit 50 --json number,title,author \
--jq '.[] | "\(.number)\t\(.author.login)\t\(.title)"'外部贡献者（非维护者）的 PR——包括被「承接 #N」重做的原始 PR——必须在 Release Notes 中致谢：条目行内 (#N, @user) + 文末「贡献者」节。识别方法与格式细则见 references/release-notes-guide.md「贡献者致谢」。
综合三个来源，按模板组织 Release Notes。模板和格式指南见 references/release-notes-guide.md。如果 config/projects.yaml 中存在 release_notes.profile，优先使用项目配置指定的结构；未配置时按项目类型选择默认结构。
第 3 步：提交并打 Tag
# 确保所有变更已提交
git status
# 打 tag
git tag "vX.Y.Z"
# ⚠️ 必须校验：tag 指向的 commit 包含版本号同步 commit。
# 重打 hotfix 时常见坑：只改了 release.yml 没把 4 处版本号文件也升到 X.Y.Z，
# 导致产物文件名仍带旧版本号（如 Folia_0.4.0_* 但 tag 是 v0.4.1）。
git show vX.Y.Z --stat | head -20
# 确认 package.json / Cargo.toml / tauri.conf.json / CHANGELOG.md 都在 commit 里
# 推送 tag 触发 CI
git push origin "vX.Y.Z"如果有同名旧 tag（如发布失败后重试）：
git push origin :refs/tags/vX.Y.Z
git tag -d vX.Y.Z 2>/dev/null
git tag vX.Y.Z
git push origin vX.Y.Z第 4 步：监控 CI 构建
# 查看构建状态
gh run list --limit 3
# 各平台 job 状态
gh run view <RUN_ID> --json jobs --jq '.jobs[] | "\(.name): \(.conclusion)"'
# 失败日志
gh run view <RUN_ID> --log-failed项目类型的特定构建产物和验证方法，见 references/ 下对应文档。
第 5 步：更新 Release Notes
CI 构建成功后，用第 2 步准备的草稿更新 GitHub Release：
gh release edit vX.Y.Z --repo <owner>/<repo> --notes "$(cat <<'EOF'
<Release Notes 内容>
EOF
)"Release Notes 正文不要再写 # <项目名> vX.Y.Z 或其他重复版本标题；GitHub Release 页面自身已经显示标题，正文应直接从摘要、升级提示或 Highlights 开始。
第 6 步：验证
# 检查产物是否完整
gh release view vX.Y.Z --json assets --jq '.assets[].name'对照 config/projects.yaml 中该项目的配置检查：
- 预期产物是否齐全（根据
platforms和auto_update推导） exclude_assets中列出的产物是否意外出现- 产物命名是否符合规范
- Release Notes 是否符合
release_notes.required_sections和release_notes.always_include约束 - 本版本合入外部贡献者 PR 时，Release Notes 是否包含致谢（行内标注或「贡献者」节）
- 产物完整矩阵对照（带自动更新项目必查）：见下表，对照产物清单逐行打勾
| 平台 | 安装包 | updater binary | .sig | latest.json entry |
|---|---|---|---|---|
| darwin-aarch64 | App_X.Y.Z_aarch64.dmg | App_aarch64.app.tar.gz | App_aarch64.app.tar.gz.sig | darwin-aarch64 |
| darwin-x86_64 | App_X.Y.Z_x64.dmg | App_x64.app.tar.gz | App_x64.app.tar.gz.sig | darwin-x86_64 |
| windows-x86_64 | App_X.Y.Z_x64-setup.exe | （NSIS 自带） | App_X.Y.Z_x64-setup.exe.sig | windows-x86_64 |
macOS .app.tar.gz / .sig 文件名不带版本号前缀（tauri-action 历史约定），Windows .exe.sig 带版本号。任何一项缺失都让该平台用户升不到 vX.Y.Z——不要 publish draft release，先修配置 / 代码再重打 tag。
第 7 步：清理
- 删除失败的 Actions runs：
gh run delete <ID> - 清理旧的 draft release（如有）
- 确认镜像同步是否成功（如已配置）
特定项目类型指南
| 项目类型 | 参考文档 |
|---|---|
| Tauri 桌面应用 | references/tauri-release.md |
检查清单
打 tag 前（强制） — 见上文 ## ⚠️ Release ≠ 测试 — 强制约束：
- 这是给真实用户装的，不是只给自己看 artifact
- CHANGELOG 有结构化的本版本条目
- 距上次 tag ≥ 24 小时
- 本次有 ≥ 1 个实质修复 / 特性 / 改动
- 已通过五问自检
发布完成后确认：
- 所有平台 / 矩阵构建全部成功
- GitHub Release 产物完整
- Release Notes 已更新，且正文没有重复的版本标题
- 外部贡献者已在 Release Notes 致谢（本版有外部 PR 合入时，含被承接的原始 PR）
- README 技能列表已同步：
check-readme-coverage.py通过（无缺行/缺链接），分节归属与描述正确（见模式 B「README 结构性同步」） - 镜像同步成功（如已配置）
- 旧的失败 Actions runs 已清理
- 项目文档已更新（TASKS / DECISIONS / CHANGELOG 等）
- tag 指向正确的 commit
© cat-xierluo, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 22 other files (scripts, references) in skills/release-workflow of cat-xierluo/legal-skills.
- SKILL.md
- CHANGELOG.md
- LICENSE.txt
- config/projects.example.yaml
- config/projects.yaml
- references/ci-troubleshooting.md
- references/monorepo-release.md
- references/release-notes-guide.md
- references/tauri-release.md
- scripts/align-suite-links.py
- scripts/build-suite-zips.sh
- scripts/build-zips.sh
- scripts/check-readme-coverage.py
- scripts/generate-release-notes.py
- scripts/release-monorepo.sh
- scripts/stage-suite-readme.py
- scripts/test-build-suite-zips.sh
- scripts/test_check_readme_coverage.py
- … and 5 more
Open the folder on GitHubat commit c077fcc
Compare with similar skills
Release Workflow next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Release Workflow this skillcat-xierluo/legal-skills | 713 | — | ~3.5k | Automated safety check: Pass | MIT | |
| Cutting A ReleaseTriliumNext/Trilium | 38k | — | ~3.2k | Automated safety check: Pass | AGPL-3.0 | |
| Mole CLI Release Flowtw93/Mole | 70k | — | ~2.5k | Automated safety check: Pass | GPL-3.0 | |
| Releaseeugene1g/agent-safehouse | 2.1k | — | ~3.5k | Automated safety check: Pass | Apache-2.0 | |
| Megaphone ReleaseKuberwastaken/megaphone | 169 | — | ~1.3k | Automated safety check: Pass | MIT | |
| Newumputun/cc-thingz | 484 | — | ~1.9k | Automated safety check: Notes | MIT |
Similar skills
Mole CLI Release Flow
tw93/Mole
Runbook for assessing and executing a Mole CLI release: distribution channels, pre-flight checks, capital-V tags, build artifacts and the handoff to curated release notes.
Release
eugene1g/agent-safehouse
Run the local Agent Safehouse release flow: inspect commits since the last published release, propose the next SemVer version and changelog, present a dry-run for confirmation, then update…
Megaphone Release
Kuberwastaken/megaphone
Prepare, validate, publish, and verify Megaphone releases. An agent skill from Kuberwastaken/megaphone.
New
umputun/cc-thingz
A skill your agent uses when user asks to create a release, cut a release, or publish a version.
Release Notes
MikalaiBarysevich/CleverSwitch
Generate GitHub release notes for unreleased CleverSwitch tags in the established repo format.
More from cat-xierluo/legal-skills
All 62 skills in this repoElements-Style Complaint Generator
cat-xierluo/legal-skills
Converts a lawyer's ordinary complaint or a described case into the Supreme People's Court's elements-style Word template, with layout checks on the result.
Lecture Performance Review
cat-xierluo/legal-skills
Analyzes raw lecture transcripts for verbal tics, pacing, time use and promise follow-through, with optional slide-by-slide comparison and cross-session tracking.
De-AI Polish for Chinese Articles
cat-xierluo/legal-skills
Detects and rewrites machine-sounding patterns in the body text of Chinese articles while keeping the author's facts, headings and legal terms intact.
GitHub Star Manager
cat-xierluo/legal-skills
Finds GitHub projects mentioned in articles or screenshots and stars them, tracks updates to your starred repos, and builds an HTML dashboard to browse them.
Legal Harness Initializer
cat-xierluo/legal-skills
Sets up or incrementally updates AGENTS.md and CLAUDE.md for legal professionals, with a minimal safety baseline and a check that a new session loads and follows the rules.
Moot Court Simulation Builder
cat-xierluo/legal-skills
Chinese-language skill that organizes a case file into a multi-role mock trial with judge, parties and clerk, producing a transcript, issue review and a to-strengthen list.
Related
Categories
Questions about Release Workflow
What does Release Workflow do?
本技能应在 GitHub 项目发布新版本时使用，覆盖版本号管理、CHANGELOG 同步、Release Notes 撰写、tag 创建、CI 构建监控、发布验证和历史清理全流程。适用于桌面应用、CLI 工具、Web 应用、库/SDK 等任何基于 GitHub 的软件项目。当用户提到"发布"、"release"、"打 tag"、"新版本"、"更新版本号"、"写 release…. Release Workflow is an agent skill from cat-xierluo/legal-skills.
When should I use Release Workflow?
Release Workflow fits situations like: tasks that involve Changelog and release notes; tasks that involve Monorepo tooling.
How do I install Release Workflow in Claude Code?
Run `npx skills add cat-xierluo/legal-skills --skill release-workflow -a claude-code`. Or copy the skill folder (skills/release-workflow in cat-xierluo/legal-skills) into .claude/skills/release-workflow in your project. Claude Code loads it when a task matches its description.
How do I install Release Workflow in Codex?
Run `npx skills add cat-xierluo/legal-skills --skill release-workflow -a codex`. Or copy the skill folder (skills/release-workflow in cat-xierluo/legal-skills) into .agents/skills/release-workflow in your project. Codex loads it when a task matches its description.
Can I use Release Workflow in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add cat-xierluo/legal-skills --skill release-workflow -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/release-workflow, .gemini/skills/release-workflow, .github/skills/release-workflow and .opencode/skills/release-workflow in your project.
What does Release Workflow need to run?
Going by SKILL.md and its folder, Release Workflow needs Python and a shell for the scripts in its folder, the command-line tools its instructions call (git, gh, npm and bash) and credentials named GITHUB_TOKEN. Our summary lists: Python 3; A Bash shell.
Does Release Workflow access the network?
SKILL.md contains no URLs. Its commands use git, gh and npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is Release Workflow safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.
What licence does Release Workflow use?
Release Workflow is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Release Workflow use?
About 3.5k tokens (SKILL.md is roughly 14k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 11k tokens, read only when the agent opens those files.
What are the alternatives to Release Workflow?
Skills that share tags, products or a category with Release Workflow: Cutting A Release (TriliumNext/Trilium, 38k stars), Mole CLI Release Flow (tw93/Mole, 70k stars), Release (eugene1g/agent-safehouse, 2.1k stars) and Megaphone Release (Kuberwastaken/megaphone, 169 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Release Workflow?
cat-xierluo (a GitHub user) maintains it in cat-xierluo/legal-skills, which has 713 GitHub stars. The repository holds 62 skills in this directory. The repository was last updated on October 7, 2026.
Source: cat-xierluo/legal-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.