gstack-upgrade

gstack-upgrade 技能概覽

gstack-upgrade 的用途

gstack-upgrade 是當你想升級 gstack 本身，而不只是修補單一工作流程步驟時會用到的技能。它會先判斷 gstack 是全域安裝還是以 vendored 形式部署，接著執行升級路徑，最後把變更內容顯示出來，讓你能快速確認結果。如果你需要一份可靠的 gstack-upgrade 指南，目標是「更新這個工具，但不要把我的設定弄壞」，這就是最適合的選擇。

誰適合安裝它

如果你在維護一套以 gstack 為核心的工作流程、仰賴存放在 ~/.claude/skills 的 Claude Code skills，或希望升級時少一點人工檢查 repo 的工作，就應該安裝 gstack-upgrade skill。對於想讓 skill 自動處理安裝型態差異，而不是自己猜測要跑全域升級還是本地升級的使用者，它尤其實用。

為什麼它不一樣

gstack-upgrade for Workflow Automation 的主要價值，在於它是以升級為導向，而不是泛用的提示詞導向。這個 skill 的設計重點放在版本感知行為、使用者確認、備份/還原邏輯，以及 migration scripts。當安裝已經有歷史紀錄，而不是乾淨狀態時，它會比一句一次性的「請幫我更新」更值得信賴。

如何使用 gstack-upgrade skill

安裝並載入上下文

如果你的環境支援，先使用目錄提供的安裝指令，然後讓 Claude Code 以名稱載入這個 skill。以此 repository 而言，文件中記載的安裝方式是：
npx skills add garrytan/gstack --skill gstack-upgrade

安裝完成後，先打開 SKILL.md。接著再讀 SKILL.md.tmpl，以及 migrations/ 裡的 migration scripts，先弄清楚實際升級步驟與各版本的特殊情況，再讓 skill 開始執行。

給 skill 正確的起始提示

一個好的 gstack-upgrade usage 提示詞應該簡短但具體，例如：「把目前安裝的 gstack 升級到最新版，並告訴我有哪些地方需要複查。」如果你已經知道安裝型態，也要直接說明，例如：「這是 ~/.claude/skills 底下的 vendored 安裝；請安全升級並保留備份。」

更強的輸入通常還會包含：

• 已知的目前版本
• 你是否希望自動升級
• 變更檔案前是否需要先確認
• 任何限制條件，例如離線作業、shell 權限有限，或自訂 skills 路徑

先讀這些檔案

若要提高決策品質，請先預覽真正驅動行為的檔案，而不只是落地頁：

• 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；如果你只是想看概念性的 changelog，則不必。最重要的輸入是安裝屬於全域、vendored，還是混合型，因為這會影響 skill 應該碰哪些路徑。如果你正在有自動核准機制的環境中執行，也要先確認 GSTACK_AUTO_UPGRADE=1 或以設定檔啟用的自動升級是否已經開啟，再呼叫這個 skill。

gstack-upgrade skill 常見問題

gstack-upgrade 只能用來升級嗎？

是。gstack-upgrade skill 的範圍就是把 gstack 移到較新的版本，並處理後續工作。它不是用來處理其他 repo 任務的通用除錯 skill，也不適合拿來取代另一個專案的客製化 migration plan。

需要是新手才能用嗎？

不用。新手只要照著安裝步驟，並提出清楚直接的需求，也可以使用；但最好的結果通常來自能說明自己安裝型態與風險容忍度的使用者。如果你不確定，就先要求一次一般升級，並開啟確認再變更。

它和一般提示詞有什麼不同？

一般提示詞可能只會請助理「升級 gstack」，但 gstack-upgrade 已經內建版本化工作流程、確認邏輯，以及能感知 migration 的行為，因此升級會更安全。當安裝歷史上有多次 migration，或 skill 需要判斷該先詢問還是自動執行時，這個差異就很重要。

什麼情況下不適合使用它？

如果你只是想看 release notes、你其實沒有在跑 gstack，或你需要的是更廣泛的系統維護工具，就不要用 gstack-upgrade。如果你希望在任何檔案變更前，先把每個 migration 都完整人工審查一遍，它也不是很好的選擇。

如何改進 gstack-upgrade skill

先提供版本與安裝資訊

影響品質最大的提升，來自於直接告訴 skill 它要升級的是什麼、安裝位置在哪裡。像「把我的全域 gstack 安裝從 v1.0 升級到最新版」就比「幫我修好」更好，因為 skill 可以直接把升級路徑對準安裝型態，避免多做不必要的偵測。

先說明你對自動化的接受程度

如果你希望 gstack-upgrade skill 跑得快，就要明講是否允許自動升級；如果你希望變更前先檢視，也要一併說清楚。這樣可以減少對確認步驟的歧義，並在遇到 UPGRADE_AVAILABLE 時，幫 skill 更容易選到較安全的分支。

留意對 migration 敏感的情況

最常見的失敗模式，是把每個安裝都當成乾淨狀態。舊版安裝可能需要修正目錄結構、遷移 resource log、調整 prompt 風格，或處理 repo 重新命名。如果你的環境有這些歷史痕跡，請在需求裡直接提到，讓升級能先驗證，而不是晚點才重新發現問題。

根據第一次結果再迭代

完成第一次升級後，確認新行為是否符合你的工作流程：安裝位置、確認風格，以及任何變動過的 prompt 預設。如果有哪裡不對，就要求只針對差異做第二次修正，例如「保留簡潔文風」、「恢復先前的升級確認行為」，或「重新執行但保留備份」。