Google Calendar

Google Calendar と連携して、イベント管理、スケジューリング、空き時間確認を行います。

インストール

依存関係: pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

セットアップ確認

インストール後、スキルが正しく構成されているか確認します:

$SKILL_DIR/scripts/google-calendar.py check

以下の項目をチェックします:

• Python 依存関係 (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
• 認証設定
• Google Calendar API への接続

何か不足していると、check コマンドがセットアップ手順を提供します。

認証

Google Calendar は OAuth 2.0 を使用します。完全なセットアップ手順については以下を参照してください:

1. GCP プロジェクトセットアップガイド - プロジェクト作成、Calendar API 有効化
2. Google OAuth セットアップガイド - 認証情報設定

クイックスタート

1. ~/.config/agent-skills/google.yaml を作成します:

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

2. $SKILL_DIR/scripts/google-calendar.py check を実行して OAuth フローをトリガーし、セットアップを確認します。

スコープまたは認証エラーが発生した場合は、OAuth トラブルシューティングガイドを参照してください。

スクリプト使用方法

各コマンドの読み取り/書き込み分類については permissions.md を参照してください。

# セットアップと認証
$SKILL_DIR/scripts/google-calendar.py check
$SKILL_DIR/scripts/google-calendar.py auth setup --client-id ID --client-secret SECRET
$SKILL_DIR/scripts/google-calendar.py auth reset
$SKILL_DIR/scripts/google-calendar.py auth status

# カレンダー
$SKILL_DIR/scripts/google-calendar.py calendars list
$SKILL_DIR/scripts/google-calendar.py calendars get CALENDAR_ID

# イベント
$SKILL_DIR/scripts/google-calendar.py events list
$SKILL_DIR/scripts/google-calendar.py events get EVENT_ID
$SKILL_DIR/scripts/google-calendar.py events create --summary TITLE --start TIME --end TIME
$SKILL_DIR/scripts/google-calendar.py events update EVENT_ID --summary TITLE
$SKILL_DIR/scripts/google-calendar.py events delete EVENT_ID

# 空き時間
$SKILL_DIR/scripts/google-calendar.py freebusy --start TIME --end TIME

すべてのコマンドは --calendar CALENDAR_ID をサポートしています (デフォルト: "primary")。時間は RFC3339 形式 (例: 2026-01-24T10:00:00Z) または YYYY-MM-DD 形式 (終日イベント用) を使用します。

完全な引数詳細と例については command-reference.md を参照してください。

例

参加者が含まれたミーティングをスケジュール

$SKILL_DIR/scripts/google-calendar.py events create \
  --summary "Team Standup" \
  --start "2026-01-25T09:00:00-05:00" \
  --end "2026-01-25T09:30:00-05:00" \
  --location "Zoom" \
  --attendees "team@example.com"

複数カレンダーの空き時間を検索

$SKILL_DIR/scripts/google-calendar.py freebusy \
  --start "2026-01-24T08:00:00-05:00" \
  --end "2026-01-24T17:00:00-05:00" \
  --calendars "primary,colleague@example.com"

今週のイベント一覧

$SKILL_DIR/scripts/google-calendar.py events list \
  --time-min "2026-01-24T00:00:00Z" \
  --time-max "2026-01-31T23:59:59Z"

エージェント向けガイダンス — ページネーション

イベント一覧取得は自動的にすべての結果をページングします。時間範囲が指定されている場合、マッチするすべてのイベントが返されます。結果が暗黙的に切り詰められることはありません。

エージェント向けガイダンス — 辞退されたイベント

イベント一覧表示時、辞退されたミーティングはデフォルトで除外されます。スクリプト出力は辞退された招待状がフィルタリングされたかを示します (例: "3 declined invitation(s) not shown")。このメッセージが表示された場合、ユーザーに辞退された招待状があることを伝え、必要に応じて表示するよう提供してください。辞退されたイベントを含めるには --include-declined で再実行してください。

エラーハンドリング

認証エラーとスコープエラーは再試行できません。 コマンドが認証エラー、不十分なスコープエラー、またはパーミッション拒否エラー (終了コード 1) で失敗した場合、停止してユーザーに通知してください。自律的に再試行または修正を試みないでください。これらのエラーはユーザー操作 (ブラウザベースの OAuth 同意) が必要です。ユーザーを OAuth トラブルシューティングガイドに誘導してください。

再試行可能なエラー: レート制限 (HTTP 429) と一時的なサーバーエラー (HTTP 5xx) は、短い待機後の再試行で成功する可能性があります。その他すべてのエラーはユーザーに報告してください。

モデルガイダンス

このスキルは構造化入出力が必要な API 呼び出しを行います。標準機能モデルが推奨されます。

トラブルシューティング

イベントが見つからない

イベント ID とカレンダー ID が正しいことを確認してください。イベント ID はカレンダーごとに一意です。

タイムゾーン問題

常に明示的なタイムゾーンオフセット付きの RFC3339 形式、または UTC (Z サフィックス) を使用してください。終日イベントの場合、YYYY-MM-DD 形式を使用し、オプションで --timezone を指定できます。