gws-people

gws-people skill の概要

gws-people skill でできること

gws-people skill は、googleworkspace/cli 内の Google People API 用ワークフローです。gws people 系のコマンドを使って、コマンドラインから連絡先、連絡先グループ、プロフィール関連レコードを管理できます。gws-people skill は、一度きりのプロンプトではなく、繰り返し実行する連絡先操作が必要なときに使います。

どんな人に向いているか

CRM Operations、管理ツール、そして連絡先データを継続的に確認・グループ化・更新する自動化タスクに適しています。API ドキュメントを手探りで読むよりも、Google People 向けに整理された CLI フローが欲しい場合に特に有用です。

導入前に押さえるべき点

gws-people の主な価値は、作業対象を特定のリソース群とコマンドパターンに絞り込めることです。gws people <resource> <method> [flags] という形に沿って作業できます。一方で、導入の障害になりやすいのは依存関係と前提コンテキストです。gws バイナリが必要であり、../gws-shared/SKILL.md にある共通の認証・セキュリティガイダンスにも従う必要があります。また、実運用で重要な API 制約、特に同一ユーザーに対する変更処理は順次実行される点にも注意が必要です。

gws-people skill の使い方

共通セットアップをインストールして確認する

npx skills add googleworkspace/cli --skill gws-people でインストールします。何かを実行する前に、共通の前提が揃っているか確認してください。../gws-shared/SKILL.md を開いて、認証、グローバルフラグ、セキュリティルールを確認します。ワークスペースにそれがない場合は、先に gws generate-skills を実行してください。gws-people の使い方は skill フォルダだけで完結するのではなく、共通の CLI 規約に依存しているためです。

コマンドパターンに合わせて依頼内容を組み立てる

よいプロンプトでは、リソース、メソッド、対象アカウントのコンテキスト、そして期待する結果を明示します。たとえば、「連絡先グループを確認するための gws people contactGroups list コマンド」や「連絡先グループを安全に作成してから名前を変更する手順」と依頼するとよいでしょう。CRM Operations 向けの gws-people では、監査、整理、セグメント分け、同期のどれを行うのかも含めて伝えてください。それによって適切なリソースとメソッドが変わります。

先に読むべきファイルを確認する

まず SKILL.md を読み、次に ../gws-shared/SKILL.md を確認します。自分のワークフローに合うか判断したいなら、最初に SKILL.md 内の API リソース一覧を読むのが有効です。実際の境界線はそこに表れています。contactGroups、otherContacts、people はサポートされていますが、この skill は汎用 CRM ではありません。

ワークフロー上の制約を踏まえて使う

gws-people は、同一ユーザーに対する書き込みを順番に行い、API がうまく扱えないバッチ前提を避けると最も力を発揮します。高い精度が必要な作業では、対象リソース、最も安全なメソッド、変更後の検証手順までセットで依頼してください。対象リソースが不明なら、いきなり変更せず、まず探索用コマンドを頼むほうが安全です。

gws-people skill の FAQ

gws-people は上級者向けだけですか？

いいえ。CLI の流れに従え、共通の gws セットアップを先に確認できるなら、初心者でも使えます。この skill は複雑なコードを書くことよりも、正しいリソースとメソッドを選ぶことに重心があります。

どんなときに gws-people を使うべきではありませんか？

幅広い CRM システムが必要な場合、UI だけで連絡先を管理したい場合、Google 以外のデータソースを扱いたい場合には向きません。People API のモデル外にある連絡先レコードへの自動化が必要なタスクにも不向きです。

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

通常のプロンプトでは、一般的な回答が返ることがあります。gws-people skill は、コマンド形のワークフロー、関連するリソース群、そして同一ユーザーへの変更リクエストは順次実行すべきという重要な制約をセットで提供します。これにより、Google Workspace の管理作業や CRM Operations での試行錯誤を減らせます。

主なインストール依存関係は何ですか？

重要なのは gws CLI と、共通の gws skill コンテキストです。この土台がない、または設定が不十分な場合、gws-people をインストールしても実用的なワークフローにはなりません。

gws-people skill を改善するには

目的を具体的に指定する

gws-people で良い結果を得るには、対象オブジェクト、実行アクション、スコープを明確にしたプロンプトが最適です。「現在の認証ユーザーの連絡先グループをすべて一覧表示してほしい」は、「連絡先について手伝って」よりずっと良い指示です。「重複なしで、特定の名前の連絡先グループを 1 つ更新してほしい」は、「グループを直してほしい」より有効です。具体性があるほど、skill は適切な People リソースを選びやすくなり、不要な手順も減ります。

最も重要な運用上の制約を含める

書き込みを伴う作業なら、安全性、順次実行、監査可能性、巻き戻し可能性のどれが必要かを明示してください。リポジトリのメモには、同一ユーザーに対する変更は順次処理する必要があると書かれており、この違いは出力品質を大きく左右します。CRM Operations の場合は、クレンジング、エンリッチメント、グルーピング、プロフィール確認のどれかも伝えると、より実務に合った提案になります。

探索から実行へ段階的に進める

gws-people では、まず read や list のコマンドで状況を把握し、その後で単一の変更操作に絞り込む流れが効果的です。最初の出力が広すぎる場合は、具体的な gws people コマンド、必要なフラグ、変更後の検証チェックまで求めてください。1 回で汎用的なワークフローを完成させようとするより、この進め方のほうが gws-people の活用精度は高くなります。