gstack-upgrade

gstack-upgrade 技能概览

gstack-upgrade 的作用

gstack-upgrade 是你在想升级 gstack 本身，而不是只修补某个单独工作流步骤时会用到的技能。它会识别 gstack 是全局安装还是 vendored 布局，执行升级路径，然后把变更点展示出来，方便你快速核对结果。如果你需要一份可靠的 gstack-upgrade 指南，目标是“更新这个工具，但不要把现有环境弄坏”，那它就很适合。

适合谁安装

如果你维护的是基于 gstack 的工作流，依赖存放在 ~/.claude/skills 下的 Claude Code skills，或者希望升级过程少做手工仓库检查，就应该安装 gstack-upgrade。它尤其适合那些想让 skill 自动处理安装类型差异，而不是靠猜测自己该跑全局升级还是本地升级的用户。

它为什么不一样

gstack-upgrade for Workflow Automation 的核心价值在于，它是围绕升级设计的，而不是通用的 prompt 处理器。这个 skill 把版本感知行为、用户确认、备份/恢复逻辑和迁移脚本都考虑了进去。这样一来，当安装历史不再是“干净状态”而是已经经历过多次变更时，它就比一次性的“请更新”提示更可靠。

如何使用 gstack-upgrade 技能

安装并加载上下文

如果你的环境支持目录的安装命令，就先用它安装，然后让 Claude Code 按名称加载这个 skill。对于这个仓库，文档里的安装方式是：
npx skills add garrytan/gstack --skill gstack-upgrade

安装后，先打开 SKILL.md。然后再阅读 SKILL.md.tmpl 和 migrations/ 里的迁移脚本，先弄清楚真实的升级步骤和按版本划分的边缘情况，再让 skill 开始执行。

给技能一个合适的起始提示

一个好的 gstack-upgrade usage 提示应该简短但具体：“把 gstack 从当前已安装版本升级到最新发布版，并告诉我是否有需要复核的地方。”如果你已经知道安装形态，也要直接说明：“这是一个位于 ~/.claude/skills 下的 vendored 安装；请安全升级并保留备份。”

更有用的输入还包括：

• 已知的当前版本
• 你是否希望自动升级
• 变更文件前是否需要确认
• 诸如离线工作、受限 shell 访问或自定义 skills 路径之类的约束

先读这些文件

如果你要判断这个 skill 值不值得用，先预览真正驱动行为的文件，而不只是落地页：

• SKILL.md：实际运行时的升级流程
• SKILL.md.tmpl：作者维护的源定义
• migrations/v0.15.2.0.sh：目录结构修复
• migrations/v1.0.0.0.sh：首次运行时的提示行为
• migrations/v1.1.3.0.sh：安装清理逻辑
• migrations/v1.17.0.0.sh 和 migrations/v1.27.0.0.sh：后续的重命名和接线变更

实用工作流建议

当你需要的是“带验证的升级”，而不是一份概念性的更新日志时，才应该用这个 skill。最关键的输入是安装是 global、vendored 还是混合形态，因为这会影响 skill 应该触碰哪些路径。如果你运行在有自动审批的环境里，在调用 skill 之前，先确认 GSTACK_AUTO_UPGRADE=1 或基于配置的自动升级是否已经启用。

gstack-upgrade 技能常见问题

gstack-upgrade 只用于升级吗？

是的。gstack-upgrade skill 的范围就是把 gstack 迁移到更新版本，并处理后续工作。它不是一个通用的仓库故障排查技能，也不能替代其他项目的自定义迁移方案。

初学者也能用吗？

可以。只要按安装步骤操作，并给出直白的请求，初学者也能用。但最佳效果通常来自能说明安装类型和风险偏好的用户。如果不确定，就让它执行一次普通升级，并开启确认。

它和普通 prompt 有什么区别？

普通 prompt 可能只是让助手“升级 gstack”，但 gstack-upgrade 内置了版本化工作流、确认逻辑，以及对迁移的感知能力，因此升级更安全。尤其当安装经历过历史迁移，或者 skill 需要判断是先询问再执行，还是自动运行时，这一点就很重要。

什么情况下不该用它？

如果你只是想看 release notes、你其实并没有在运行 gstack，或者你需要的是更广泛的系统维护工具，就不要用 gstack-upgrade。如果你想在任何文件变更发生前，先对每一次迁移做完全手工审查，它也不合适。

如何改进 gstack-upgrade 技能

先给出版本和安装信息

最大的质量提升，来自一开始就告诉 skill 它要升级什么、安装在哪里。“把我的全局 gstack 安装从 v1.0 升级到最新版本”就比“修一下它”更有用，因为这样 skill 可以把升级路径和安装类型对齐，避免做不必要的检测。

说明你能接受多少自动化

如果你希望 gstack-upgrade skill 运行得更快，就直接说明是否允许自动升级。如果你希望在改动前先审查，也要明确说出来。这样可以减少确认步骤上的歧义，并帮助 skill 在遇到 UPGRADE_AVAILABLE 时选择更安全的分支。

注意迁移敏感场景

最常见的失败模式，是默认所有安装都是干净的。旧安装可能需要目录结构修复、resource-log 迁移、提示语风格变更，或者仓库重命名处理。如果你的环境里存在这些历史痕迹，就在请求里提出来，让升级去验证这些点，而不是等到最后才重新发现问题。

基于第一次结果继续迭代

第一次升级完成后，检查新行为是否符合你的工作流：安装位置、确认风格，以及是否有改过的 prompt 默认值。如果哪里不对，就发起一次只修正不匹配项的后续请求，比如“保持简洁措辞”“恢复之前的升级确认行为”或“在保留备份的前提下重新运行”。