gws-shared

gws-shared 技能總覽

gws-shared 是做什麼用的

gws-shared 技能是 gws 工作流程自動化的共用層：它能幫你在 Google Workspace CLI 任務中，穩定一致地使用共用驗證、全域旗標與輸出處理。若你想要的是可重複的命令模式，而不是每次都臨時想一套提示詞，這個技能最實用。

誰適合安裝

如果你正在圍繞 gws 建立腳本、代理程式或操作型工作流程，並且需要一個可靠的登入、service account 驗證、分頁、dry run 和安全輸出格式參考，就應該安裝 gws-shared 技能。若你只需要單次性的 CLI 指令，且不打算重複使用這種模式，這個技能的價值就比較有限。

實際上會改變什麼

gws-shared skill 的核心價值，是減少你對命令結構與旗標的猜測。它提供一套穩定的表達方式，讓你清楚指出：要操作哪個 service/resource、要呼叫哪個 method、哪些旗標屬於全域設定，以及輸出要選 JSON、table、YAML 還是 CSV。

如何使用 gws-shared 技能

安裝並驗證 gws-shared 技能

repo 說明指出，gws binary 必須先在你的 $PATH 裡；這個技能本身是共用參考資料，不是 binary 安裝程式。對於 gws-shared install，請先確認 gws 可用，再在自動化中採用這個命令模式前，先把 SKILL.md 當作主要依據來閱讀。

先讀這些檔案

先從 skills/gws-shared/SKILL.md 開始，再查看 repository 層級的 README 或鄰近文件，確認實際的 gws 安裝選項與環境設定。這個 repo 的 skill 路徑很精簡，也沒有 helper scripts 或支援資料夾，因此 skill 本體才是重點來源：驗證、旗標、語法與安全規則都在裡面。

把模糊目標改寫成可用提示詞

一個好的 gws-shared usage 提示詞，應該包含目標 service、resource、method、期望輸出格式，以及動作是否只讀或可能具破壞性。比如不要只說「管理使用者」，而是改成：「使用 gws-shared 以 table 格式列出 Workspace users，避免寫入，並在可用時說明最安全的 --dry-run 指令。」

需要遵循的實際命令格式

核心語法是 gws <service> <resource> [sub-resource] <method> [flags]。用 method flags 來縮小呼叫範圍：--params 用於查詢參數，--json 用於 request body，--upload 用於檔案內容，-o 用於二進位輸出，而 --page-all 只有在你預期會有多頁結果時才使用。對於 gws-shared for Workflow Automation，也要明確說明這一步是互動式、基於 service account，還是完全自動化，這樣技能才能選對驗證與輸出行為。

gws-shared 技能 FAQ

gws-shared 只適合進階使用者嗎？

不是。gws-shared skill 對初學者其實也很有幫助，因為它消除了驗證與命令格式上的歧義。主要前提是你已經安裝好 gws，並且知道要操作哪一個 Google Workspace 物件。

什麼情況下不該用它？

如果你需要的是從零開始學 gws product 的教學，或你的任務超出 CLI 所支援的 service/resource 模型，就不適合用 gws-shared。當你只想要一段不含命令就能直接使用的通用 API 說明時，它也不是最合適的選擇。

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

一般提示詞可能只會描述目標，但 gws-shared guide 的行為會提供共用的操作規則：驗證選項、安全旗標、輸出模式與分頁控制。這通常代表自動化時重試次數更少，格式漂移也更少。

主要界線是什麼？

這個技能只支援在 SKILL.md 文件中說明的 gws CLI 慣例內的讀寫工作流程。你仍然需要自己選對憑證、對寫入或刪除操作遵守確認流程，並避免在輸出中暴露秘密資訊。

如何改進 gws-shared 技能

補上技能缺少的上下文

最好的輸入會清楚寫出 service、resource、method 和輸出目標。例如：「將 Calendar events 匯出成 CSV，使用 --page-all，限制為只讀呼叫，並讓回應適合後續解析。」這比「幫我總結行事曆資料」更好，因為它能讓 gws-shared 選到正確的旗標與流程。

一開始就說明安全與自動化限制

由於 repo 強調安全規則，請先告訴技能這個任務是否可能修改資料、是否應該使用 --dry-run，以及回應是否必須經過清理。這在 gws-shared for Workflow Automation 特別重要，因為模糊的需求有時會意外產生可寫入的命令。

先迭代第一個命令，不要一次改整個工作流程

如果第一個輸出已經接近，但還不夠精準，請一次只調整一個變數：驗證模式、格式、分頁或 body 參數。改進 gws-shared usage 最快的方法，是先修正命令結構，再擴大範圍；特別是在處理二進位輸出、上傳，或多頁回應時更是如此。