gws-drive

gws-drive skill の概要

gws-drive ができること

gws-drive は、Google Workspace CLI 向けの Google Drive skill です。コマンドラインからファイル、フォルダ、共有ドライブ、そしてそれに関連する Drive API ワークフローを扱えます。リソース名、必須フィールド、権限制約を推測で埋めなくて済むよう、skill 固有のガイダンスも用意されています。

どんな人に向いているか

Backend Development、自動化、ops の文脈で、スクリプトやエージェントワークフローから再現性のある Drive 操作を行いたいなら、gws-drive skill が向いています。単発のプロンプトではなく、CLI を土台にした処理で Drive タスクを回したいとき、特にアップロード、メタデータを意識した操作、API ベースの問い合わせで役立ちます。

インストール前に確認すべきこと

gws-drive の価値は、対応範囲の広さよりも信頼性にあります。エージェントを適切な Drive リソースと正しいリクエスト形に導いてくれるからです。導入時に最もつまずきやすいのは認証と共有設定で、skill はより広い gws 環境と、フラグやセキュリティルールを定める gws-shared の指示に依存します。

gws-drive skill の使い方

インストールと前提条件の確認

Google Workspace CLI の文脈で gws-drive skill をインストールし、まず共有前提条件の ../gws-shared/SKILL.md を確認してください。skill のメタデータは gws バイナリが利用可能であることも前提にしているため、Drive ワークフローを試す前に CLI 自体が動くか検証する必要があります。実務的には、セットアップ後に gws drive --help を見て、skill のリソース一覧と照合するのが有効です。

正しい入力の形から始める

gws-drive の基本パターンは gws drive <resource> <method> [flags] です。そのため、プロンプトでは対象リソース、実行するアクション、そして出力条件を具体的に指定する必要があります。良い入力の例は「アクセス可能な共有ドライブを一覧表示し、name と id だけを返し、trash は除外して」です。悪い入力は「Drive を確認して」です。Backend Development 向けに gws-drive ガイドを使うなら、識別子、親フォルダ、権限やスコープの前提も最初から明示してください。

先に読むべきファイル

まず SKILL.md を読み、その次に ../gws-shared/SKILL.md を確認してください。認証、グローバルフラグ、セキュリティ挙動はそちらが管理しています。この repo の範囲には、頼れる補助スクリプトやサポート用フォルダはありません。そのため、skill ファイル自体が一次情報です。特に API リソースの各セクションと、補助コマンド +upload に注意してください。一般的な Drive ドキュメントから推測するのではなく、想定ワークフローがそのまま示されています。

より良い結果を出すワークフロー

流れは 3 段階です。まずリソースを決め、次に method を絞り込み、最後に API レスポンスに影響する flag だけを追加します。たとえば Drive アカウント情報を取得するなら、about.get では fields が必要だと明記するべきですし、アップロード関連の作業では自動メタデータを使いたい場合に補助コマンドへ誘導するのが適切です。これが gws-drive の基本原則です。可能な限り広い応答ではなく、最小限で役に立つ応答を求めてください。

gws-drive skill の FAQ

gws-drive は基本操作だけの skill ですか？

いいえ。gws-drive は Drive の主要リソースだけでなく、自動化で重要になる特定の API 挙動もカバーしています。たとえば about.get には fields が必要であることや、承認者のみが扱える制約を伴う access proposal の処理などです。そのため、単なる Drive の一般説明よりも、正しい API 形が重要なタスクで適しています。

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

手作業で一度だけ Drive のコツを知りたいだけなら、gws-drive skill は不要です。また、gws CLI と共有認証のセットアップがまだ整っていない場合も向きません。Drive 操作そのもの以外のタスクにも不向きです。skill は一般的な Workspace の相談ではなく、リクエスト構築と CLI 実行に最適化されているためです。

初心者でも使いやすいですか？

はい。具体的な Drive の目的を説明できるなら使いやすいです。skill は resource-method パターンと重要な注意点を示してくれるため、推測はかなり減ります。ただし初心者でも、対象のファイル、フォルダ、共有ドライブ、または権限シナリオは提示する必要があります。そこが曖昧だと、エージェントがぼんやりしたコマンドを出したり、広すぎる API 呼び出しを選んだりします。

通常のプロンプトと何が一番違いますか？

通常のプロンプトは Drive の概念説明に寄りがちですが、gws-drive は実際の CLI と API リソースに根ざしたワークフローを提供します。これは、決定的なコマンド、正しい field の選択、初回実行で失敗してはいけない権限考慮の操作が必要なときに特に重要です。

gws-drive skill の改善方法

エージェントに正確な Drive コンテキストを渡す

最良の結果を得るには、1 文の中で resource、action、scope を明示してください。例: 「gws-drive を使って folder abc123 内の files を一覧表示し、id、name、mimeType、modifiedTime を返し、trash の項目は含めない」。これは「documents を探して」と頼むよりずっと強力です。検索のあいまいさを減らし、不要な API 出力も避けられます。

API 呼び出しを変える制約を明示する

shared drives が必要か、特定の folder か、access proposal か、account-level の情報かを伝えてください。gws-drive では、その違いで必要な権限やレスポンス要件が変わります。これを省くと、最初の出力は fields の不足、承認者アクセスの不足、またはクエリが広すぎることを理由に失敗しやすくなります。

コマンドから結果へ反復する

最初の出力が広すぎるなら、任意の出力を減らして、必要な識別子を正確に追加してください。失敗した場合は、認証の問題か、gws-shared にある前提条件の不足か、resource-method の組み合わせ違いかを確認します。gws-drive のガイドで最短なのは、タスク自体を変える前に、まずコマンドの形を正すことです。