gws-drive

Google Drive の中身を、エージェントに命令で扱わせたいときに使います。ファイルを探す、メタデータを読む、書き出す、コメントや共有の設定を見る、といった作業です。

このスキルは、Google Workspace の CLI gws に付いてくる SKILL.md の 1 つです。本文は Drive API（v3）の資源と命令の一覧で、エージェントはそれを見て gws drive <資源> <命令> を組み立てます。

本文に並ぶ API の資源

14

資源の下に並ぶ命令

53

補助の命令（+upload）

1

同梱ファイル（2026-10-23 時点）

0 件

一覧は Google の API の定義から作られている

gws は、コマンドの一覧を手で持っていません。README によると、Google の Discovery Service を実行時に読んで、命令の全体を組み立てます。Drive に命令が増えれば、CLI の側も自動で追いつきます。

この SKILL.md も、CLI の gws generate-skills が同じ情報から書き出したものです。本文の命令の説明は、Drive API の説明文がほぼそのまま入っています。

主な資源

• files作成・複製・取得・一覧・更新・書き出し・ダウンロードなど 11 の命令
• permissions共有の設定。作成・削除・取得・一覧・更新
• drives共有ドライブ。作成・取得・一覧・更新・隠す・戻す
• comments / repliesファイルへのコメントと返信
• revisionsファイルの版。一覧・取得・更新・削除
• changes / channels変更の取得と、変更の通知の購読・停止

ほかに about（利用者と Drive の情報）、accessproposals（アクセスの申請）、approvals、apps、operations、teamdrives があります。teamdrives の 4 つの命令は廃止扱いで、drives を使うよう書かれています。

引数は推測させず、gws schema で確かめさせる

本文の締めは、API の命令を呼ぶ前に中身を確かめる手順です。gws drive --help で資源と命令を見て、gws schema drive.<資源>.<命令> で必須の引数・型・既定値を確かめます。

その結果から --params（URL と問い合わせの値）と --json（要求の本体）を組み立てる、という流れです。命令の名前だけ知っていて引数を当て推量する、という失敗を減らす作りです。

一覧に書かれている Drive の癖

命令の説明には、知らないとつまずく Drive の性質がいくつか入っています。

• files list は、既定でゴミ箱の中のファイルも返す。除くには trashed=false を問い合わせに入れる
• files export で書き出せる中身は 10 MB まで
• about get と comments の多くの命令は、fields の指定が必須
• revisions list は、編集の多い文書・表・スライドでは古い版が抜けることがある

• Drive にファイルを上げるだけ補助の命令 +upload 専用の gws-drive-upload がある
• メールを送るGmail は別のスキル。送るだけなら gws-gmail-send
• gws を入れられない環境本文は gws の命令しか書いていない
• Drive の画面で済む 1 回きりの操作認証の準備のほうが重い

ファイルの中身を手元で編集したいだけなら、このスキルは遠回りです。ダウンロードと書き出しまでは扱いますが、Word や Excel の中身を読み書きする手順は入っていません。

メールの送信は gws-gmail-send の担当です。同じ gws の部品なので、認証は共通で使えます。

削除の命令は一覧から外してある

原本のコード（generate_skills.rs）を検索した範囲では、この除外の一覧が使われているのはスキルの生成だけでした。エージェントに「削除の命令は無い」と思い込ませる仕組みではありません。削除をさせたくないなら、プロンプトではっきり禁じてください。

一覧に残っている命令にも、取り消しにくいものがあります。revisions delete は、画像や動画など中身がバイナリのファイルの版を完全に消します（文書・表・スライドの版と、最後に残った版は消せません）。

共有の設定は同時に変えると最後の 1 件だけ残る

permissions の作成・削除・更新には、同じファイルへの同時の操作に対応しておらず、最後の更新だけが反映される、という警告が付いています。

エージェントに複数の人への共有を並べて付けさせると、一部が消える形で終わるおそれがあります。共有の付け外しは 1 件ずつ、結果を確かめながら進めさせてください。共有はファイルを外の人に見せる操作なので、宛先も先に人が確かめるのが安全です。

書き込みの前に人の確認を取る決まりは、別のファイルにある

本文の冒頭は、認証・共通の旗・安全の決まりを ../gws-shared/SKILL.md で読め、と指示しています。安全の決まりは、秘密の値を出さない、書き込みと削除の前に必ず利用者に確かめる、壊す操作には --dry-run を使う、の 3 つが中心です。

このスキルだけを入れると、gws-shared は手元にありません。本文は、無ければ gws generate-skills で作れと書いています。この命令は既定で skills/ にスキル一式を書き出すので、作業中のリポジトリの中で走らせないよう気を付けてください。

OAuth の範囲

README によると、検証を受けていない OAuth のアプリ（テストの状態）では、同意できる範囲が約 25 個に制限されます。recommended の組は 85 個を超えるので通らず、gws auth login -s drive,gmail,sheets のように使うサービスを絞れ、とあります。

コード（auth_commands.rs）の既定の範囲は、drive・gmail.modify・tasks など 7 つです。読むだけの用途なら、gws auth login --readonly で drive.readonly などの読み取りの組を選べます。調べものだけをさせるなら、こちらで始めるのが筋です。

書かれている外部通信とコマンド

SKILL.md に書かれているのは gws の命令の実行で、どれも Google の API と通信します。--page-all は結果を自動でページ送りし、既定で最大 10 ページ、ページの間に 100 ミリ秒の間を置きます。

API の応答は --sanitize で Google Cloud の Model Armor に通して、埋め込まれた指示（プロンプトインジェクション）を検査できます。Drive のファイル名やコメントは他人が書いたものも含むので、検討の価値があります。

開発中で、Google の公式の製品ではない

README は、開発の途中で v1.0 に向けて互換性の無い変更があり得る、と明記しています。末尾には、Google が公式に支える製品ではない、という断り書きがあります。本文の版は 0.22.5 です（2026-10-23 時点）。ライセンスは Apache-2.0 です。

このスキルだけ入れれば Drive を操作できますか

できません。gws の実行ファイルと、OAuth の資格情報が別に要ります。README の手順では、gcloud がある環境なら gws auth setup でプロジェクトの作成から済ませ、無ければ Google Cloud Console で OAuth のクライアントを作って gws auth login を流します。認証と安全の決まりを書いた gws-shared も、一緒に入れておくのが前提です。

ファイルを消させないようにできますか

スキルの文面からは削除の命令が外してありますが、CLI の命令としては残っています。プロンプトで削除を禁じるのに加えて、読むだけの作業なら gws auth login --readonly の読み取りの範囲で認証しておくと、書き込みの要求そのものが通りません。

ゴミ箱のファイルが一覧に混ざります

Drive API の files list は、既定でゴミ箱の中も返します。本文にもそう書かれていて、trashed=false の問い合わせで除くよう案内しています。引数の正確な形は gws schema drive.files.list で確かめさせてください。

結果を表の形で見られますか

共通の旗 --format で、既定の JSON のほかに table・yaml・csv を選べます。エージェントに処理させるなら JSON のまま、人が目で確かめるなら table が向いています。