gws-forms

gws-forms skill 總覽

gws-forms 的用途

gws-forms 是透過 gws 指令讀寫 Google Forms 的 Google Workspace CLI skill。它能幫你檢視表單結構、建立空白表單、分步更新表單內容，並且在不猜 API 欄位的情況下處理各種表單相關操作。

適合誰使用

gws-forms skill 最適合已經在 Google Workspace 自動化流程中工作，且需要穩定執行 Forms API 的 agents 與使用者。當你想要可重複的表單建立、批次更新，或以程式化方式檢查表單，而不是手動點擊 Forms UI 時，它特別有用。

為什麼這個 skill 很重要

gws-forms for Workflow Automation 的主要價值在於它把真實的 API 工作流程完整攤開，包括 method discovery 與以 schema 為基礎的輸入建構。這很重要，因為建立表單不是一步到位：forms.create 只會先建立一個空表單，接著還要用 forms.update 類型的操作把題目與設定補上。

你需要先知道的限制

這個 skill 不是那種「丟一句需求就幫你生出表單」的泛用包裝。它依賴 gws CLI，需要共用的 Google Workspace 驗證與安全設定，並且會遵循 repo 裡的 Forms API 限制。如果你要的是較自由的對話式草稿，而不是精準的 API 操作，直接下 prompt 反而可能更簡單。

如何使用 gws-forms skill

安裝與前置設定

要做 gws-forms install，請使用 skill metadata 裡提供的 CLI：npx skills add googleworkspace/cli --skill gws-forms。在執行 Forms 指令前，先依照 skill 檔案的指示閱讀 ../gws-shared/SKILL.md，因為驗證、全域 flags 與安全規則都放在那裡。如果找不到那個 shared 檔案，先執行 gws generate-skills。

先從 method discovery 開始

最可靠的 gws-forms usage 模式是：先檢視，再呼叫。先用 gws forms --help 瀏覽可用的資源與方法，再用 gws schema forms.<resource>.<method> 確認必要參數、型別與預設值，然後再開始組 flags。這樣可以避免格式錯誤的請求，也能讓你的 prompt 或任務更貼近實際 API 結構。

把模糊目標轉成可執行的請求

好的 gws-forms guide 輸入，會描述你在 API 層級真正想做什麼，而不只是商業目標。例如，不要只說「做一份回饋表單」，而是要提供標題、文件標題、預計的題型、是否要先保持空白，以及是否需要發佈設定或回應相關操作。這樣 skill 才有足夠結構判斷該呼叫 forms.create、forms.batchUpdate，或是其他 method。

先閱讀這些檔案與輸出

先看 SKILL.md，再檢查它指向的 shared parent skill 檔與 CLI help/schema 輸出。在這個 repo 裡，skill 本體很精簡，也沒有 helper folders，所以 SKILL.md 搭配 gws forms --help 與 gws schema 就是主要依據。如果你的流程會參考相鄰的 Google Workspace skills，可以對照它們的模式，但不要直接假設它們的欄位名稱或執行順序也適用於這裡。

gws-forms skill 常見問題

gws-forms 主要是用來建立表單嗎？

是，但只是在 API 的意義上。gws-forms 支援讀取與寫入表單，而且建立流程本來就是分階段進行：先建立外殼，再在之後加入題目或更新。如果你期待一個 prompt 就生成已填滿所有欄位的完整表單，這和 repo 的工作流程並不一致。

我需要 gws CLI 才能使用嗎？

是。這個 skill 明確要求 gws binary，而 skill 檔案中顯示的指令介面是 gws forms <resource> <method> [flags]。如果你的環境無法執行 CLI，或無法對 Google Workspace 完成驗證，這個 skill 就無法照原意使用。

這比一般 prompt 更好嗎？

如果是 API 工作，答案是肯定的。一般 prompt 可以描述表單內容，但 gws-forms skill 能夠用 schema 支援的參數去執行真正的 resource 與 method 呼叫，減少猜測與壞請求。當你還在發想內容時，用 prompt；當你需要表單動作真的執行時，用這個 skill。

什麼情況下不該使用？

如果你只是想快速草擬問卷題目、沒有 Workspace 憑證，或是你的需求超出 Forms API 範圍，就不要用 gws-forms。當你想跳過指令檢視、只靠自由形式自然語言完成工作時，它也不是最佳選擇。

如何改進 gws-forms skill

提供 API 形狀的輸入

最好的結果來自能清楚指定目標 resource、method 和所需欄位的輸入。請包含表單標題、document_title 是否應該不同，以及你是在建立新表單、讀取，還是更新。例如，「建立一份標題為 X 的表單，先保持空白，然後加入 5 題單選題」就比「做一份問卷」強得多。

尊重先建立、再更新的行為

常見失敗模式是要求一步完成整份表單，但 API 在建立時只允許部分資料。repo 也指出，forms.create 只會複製 form.info.title 和 form.info.document_title，建立時不允許 description、items 和 settings。想提升輸出品質，就要一開始先規劃好第二步。

用 schema 輸出消除歧義

如果第一次嘗試失敗，請重新檢查 gws schema，確認 method signature 與參數名稱完全正確，然後用那些欄位重寫請求。這是提升 gws-forms usage 最快的方法，因為它會把你的假設換成 CLI 真正期待的結構。

用更小的操作逐步迭代

當表單變更很複雜時，把它拆成更小的動作：檢視、建立、更新、驗證。這種流程可以減少 batch update 的錯誤，也更容易看出問題是輸入有誤、不支援的欄位，還是你的意圖和 Forms API 之間有落差。