gws-forms

gws-forms skill の概要

gws-forms でできること

gws-forms は、gws コマンドを使って Google Forms を読み書きするための Google Workspace CLI skill です。フォームのスキーマ確認、空のフォーム作成、段階的なフォーム内容の更新、フォーム関連操作の管理を、API フィールドを推測せずに行えるようにします。

どんな人に向いているか

gws-forms skill は、すでに Google Workspace の自動化フローで作業していて、Forms API を確実に実行したいエージェントやユーザーに向いています。Forms UI を手で操作するのではなく、再現性のあるフォーム作成、バッチ更新、プログラムによる確認をしたいときに特に有効です。

この skill が重要な理由

gws-forms for Workflow Automation の主な価値は、メソッドの探索やスキーマに基づく入力構築を含め、実際の API ワークフローをそのまま扱える点にあります。フォーム作成は一発で完結しません。forms.create では空のフォームしか作れず、その後に forms.update 系の操作で項目や設定を追加していく必要があります。

知っておくべき主な制約

この skill は、単に「プロンプトからフォームを作る」ための汎用ラッパーではありません。gws CLI への依存があり、Google Workspace 共通の認証・セキュリティ設定が必要で、リポジトリ内の Forms API 制約にも従います。正確な API 操作よりも幅広い会話的な下書きが欲しいだけなら、通常のプロンプトのほうが簡単です。

gws-forms skill の使い方

インストールと事前準備

gws-forms install では、skill のメタデータに記載された CLI を使います: npx skills add googleworkspace/cli --skill gws-forms。Forms コマンドを実行する前に、skill ファイルの指示に従って ../gws-shared/SKILL.md を確認してください。認証、グローバルフラグ、セキュリティルールはそこにまとまっています。共有ファイルが見当たらない場合は、先に gws generate-skills を実行します。

まずメソッドを見つける

gws-forms usage の最も確実な流れは、先に確認してから呼び出すことです。gws forms --help で利用可能な resource と method を確認し、その後 gws schema forms.<resource>.<method> を実行して、必要なパラメータ、型、デフォルト値を見てからフラグを組み立てます。これにより、不正なリクエストを防ぎ、プロンプトやタスクを実際の API 形状に合わせられます。

漠然とした目的を実行可能なリクエストに変える

良い gws-forms guide の入力は、業務目標だけでなく API レベルで何をしたいかまで書きます。たとえば「フィードバックフォームを作って」ではなく、タイトル、document title、想定する質問タイプ、フォームを空のまま開始するかどうか、公開設定や回答関連の操作が必要かどうかまで伝えます。そうすれば、この skill は forms.create、forms.batchUpdate、または別の method のどれを呼ぶべきか判断しやすくなります。

まず読むべきファイルと出力

最初に SKILL.md を読み、その後で、そこから案内される共有の親 skill ファイルと CLI の help/schema 出力を確認します。この repo では skill 本体はコンパクトで、補助フォルダもありません。したがって、SKILL.md と gws forms --help、gws schema が主な正本です。近接する Google Workspace skill を参考にする場合でも、field 名や処理順がここにも当てはまるとは限らないので注意してください。

gws-forms skill FAQ

gws-forms は主にフォーム作成向けですか？

はい。ただし、API の意味でのフォーム作成です。gws-forms はフォームの読み書きに対応していますが、作成は意図的に段階化されています。最初に器だけ作り、その後で項目や更新を追加します。すべての field が埋まった完成版のフォームを、1 回のプロンプトで生成したいなら、この repo のワークフローとは合いません。

使うには gws CLI が必要ですか？

はい。skill では gws バイナリが明示的に必要で、skill ファイルに示されているコマンド表面は gws forms <resource> <method> [flags] です。環境で CLI を実行できない、または Google Workspace に認証できない場合、この skill は意図した通りには使えません。

普通のプロンプトより優れていますか？

API 作業なら、はい。普通のプロンプトでもフォームの内容を説明できますが、gws-forms skill なら schema に裏付けられたパラメータで実際の resource/method 呼び出しを実行できるため、推測や壊れたリクエストを減らせます。内容を考える段階ではプロンプトを使い、実際にフォーム操作を行いたいときにこの skill を使ってください。

使わないほうがいいのはどんなときですか？

アンケート設問の下書きを素早く作りたいだけの場合、Workspace の認証情報がない場合、Forms API の範囲外のワークフローが必要な場合は、gws-forms を使わないでください。コマンドの確認を飛ばして、自然言語だけで進めたいときにも適していません。

gws-forms skill の改善方法

API らしい入力を与える

最良の結果は、対象 resource、method、欲しい field を明確にした入力から得られます。フォームのタイトル、document_title を別にするかどうか、新規作成なのか、読み取りなのか、更新なのかを含めてください。たとえば、「X というタイトルのフォームを作成し、空のままにしてから 5 問の多肢選択式質問を追加して」は、「アンケートを作って」よりずっと強い指定です。

作成と更新を分ける前提を守る

よくある失敗は、API が作成時には部分的なデータしか受け付けないのに、1 回で完成形のフォームを求めてしまうことです。リポジトリでは、forms.create は form.info.title と form.info.document_title しかコピーせず、作成時には description、items、settings を許可しないと明記されています。最初から 2 段階目まで計画しておくと、出力品質が上がります。

schema 出力であいまいさをなくす

最初の試行が失敗したら、gws schema で該当 method の正確なシグネチャと parameter 名を再確認し、その field を使って request を書き直してください。これは、CLI が想定する構造と同じものに合わせられるため、gws-forms usage を改善する最短ルートです。

操作を小さく分けて反復する

フォーム変更が複雑なときは、確認、作成、更新、検証のように小さな操作に分けます。この流れにすると、バッチ更新でのエラーが減り、問題が不正な入力なのか、未対応 field なのか、意図と Forms API の不一致なのかを切り分けやすくなります。