用途：指导 clickup-cli 的版本发布，覆盖版本号升级、npm 发布、Homebrew tap 更新、发布说明撰写与 agent skill 同步。
版本号规则：Bug 修复用 patch（x.y.Z），向后兼容的新功能用 minor（x.Y.0），破坏性变更用 major（X.0.0）。
发布前检查：npm run typecheck、npm run lint、npm test（含版本同步测试）、npm run build 均需通过；新增命令必须加入 src/commands/metadata.ts，否则补全测试会失败。
发布步骤：先单独提交功能或修复改动，不要与版本升级混在同一提交；用 npm version <version> --no-git-tag-version 升级版本；运行 node --import tsx scripts/sync-command-docs.ts 同步 docs/commands.md、skills/clickup-cli/SKILL.md 的版本头与版本检查提示、.claude-plugin/plugin.json 的版本字段；提交并打标签后推送 main 与 tags；用 gh run watch 等待 release.yml 完成，该工作流执行 typecheck、test、build、npm publish（OIDC）和创建 GitHub Release。
常见失败：npm ci 因 peer 依赖冲突失败（.npmrc 已设 legacy-peer-deps=true）；补全测试失败通常是 metadata.ts 缺少新命令或参数；npm publish 报 already published 说明该版本已存在，需升级到下一版本。修复后可 amend 提交、删除旧标签重新打标签并强制推送。
发布说明：用 gh release edit 写入，风格为每个功能一个 H2、附 2-3 个代码示例、底部写测试数量、不使用 emoji。
Homebrew：从 npm registry 下载 tgz 计算 sha256，更新 homebrew-tap 中 Formula/clickup-cli.rb 的版本 URL 与 sha256 后提交推送。
同步技能：cp skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md。
需避免：在同步脚本前提交、漏加新命令到 metadata.ts、把版本升级与功能改动放在同一提交、未先删除旧标签就强制推送标签。