google-calendar

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 への接続

不足している項目がある場合、確認コマンドがセットアップ手順を表示します。

認証

Google Calendar では認証に OAuth 2.0 を使用します。セットアップの詳しい手順については、次を参照してください。

1. GCP Project Setup Guide - プロジェクトの作成と Calendar API の有効化
2. Google OAuth Setup Guide - 認証情報の設定

クイックスタート

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 を参照してください。

# Setup and auth
$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

# Calendars
$SKILL_DIR/scripts/google-calendar.py calendars list
$SKILL_DIR/scripts/google-calendar.py calendars get CALENDAR_ID

# Events
$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

# Availability
$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 "[email protected]"

複数のカレンダーから空き時間を探す

$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,[email protected]"

今週のイベントを一覧表示する

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

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

イベント一覧では、すべての結果が自動的にページネーションされます。期間を指定すると、件数にかかわらず条件に一致するすべてのイベントが返され、結果が通知なく切り捨てられることはありません。

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

イベントを一覧表示すると、辞退した会議はデフォルトで除外されます。辞退した招待がフィルタリングされた場合、スクリプトの出力にその旨が表示されます（例：「辞退した招待が 3 件表示されていません」）。この通知が表示された場合は、辞退した招待があることをユーザーに伝え、希望する場合は表示できることを案内してください。辞退したイベントを含めるには、--include-declined を付けて再実行します。

エラー処理

認証エラーとスコープエラーは再試行できません。 コマンドが認証エラー、不十分なスコープのエラー、または権限拒否エラー（終了コード 1）で失敗した場合は、処理を停止してユーザーに伝えてください。ユーザーの操作（ブラウザー上での OAuth 同意）が必要なエラーであるため、再試行したり、自律的に問題を修正しようとしたりしないでください。ユーザーにはOAuth トラブルシューティングガイドを案内してください。

再試行可能なエラー：レート制限（HTTP 429）と一時的なサーバーエラー（HTTP 5xx）は、少し待ってから再試行すると成功する場合があります。それ以外のエラーはすべてユーザーに報告してください。

モデル向けガイダンス

このスキルでは、構造化された入力／出力を必要とする API 呼び出しを行います。標準的な能力を持つモデルを推奨します。

トラブルシューティング

イベントが見つからない

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

タイムゾーンの問題

タイムゾーンオフセットを明示した RFC3339 形式、または UTC（Z サフィックス）を必ず使用してください。終日イベントの場合は YYYY-MM-DD 形式を使用し、必要に応じて --timezone を指定します。