name: google-calendar
description: Manage Google Calendar events and calendars. List, create, update, and delete events, check availability, and organize schedules. Use when working with Google Calendar management.
metadata:
author: odyssey4me
version: "0.1.0"
license: MIT

Google Calendar

Interact with Google Calendar for event management, scheduling, and availability checking.

Installation

1. Install Python dependencies:
   bash pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

2. Download the skill from Releases or use directly from this repository.

Setup Verification

After installation, verify the skill is properly configured:

python scripts/google-calendar.py check

This will check:
- Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
- Authentication configuration
- Connectivity to Google Calendar API

If anything is missing, the check command will provide setup instructions.

Authentication

Google Calendar uses OAuth 2.0 for authentication. For complete setup instructions, see:

1. GCP Project Setup Guide - Create project, enable Calendar API
2. Google OAuth Setup Guide - Configure credentials

Quick Start

1. Create ~/.config/agent-skills/google.yaml:
   yaml oauth_client: client_id: your-client-id.apps.googleusercontent.com client_secret: your-client-secret

2. Run python scripts/google-calendar.py check to trigger OAuth flow and verify setup.

OAuth Scopes

The skill requests granular scopes for different operations:

Scope Errors

If you encounter "insufficient scope" errors, revoke your token and re-authenticate:

1. Revoke at https://myaccount.google.com/permissions
2. Clear token: keyring del agent-skills google-calendar-token-json
3. Re-run: python scripts/google-calendar.py check

Commands

check

Verify configuration and connectivity.

python scripts/google-calendar.py check

This validates:
- Python dependencies are installed
- Authentication is configured
- Can connect to Google Calendar API
- Displays your primary calendar information

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

python scripts/google-calendar.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Credentials are saved to ~/.config/agent-skills/google-calendar.yaml.

calendars list

List all calendars for the authenticated user.

# List calendars
python scripts/google-calendar.py calendars list

# Output as JSON
python scripts/google-calendar.py calendars list --json

Arguments:
- --json: Output as JSON

calendars get

Get details for a specific calendar.

# Get primary calendar
python scripts/google-calendar.py calendars get primary

# Get specific calendar by ID
python scripts/google-calendar.py calendars get CALENDAR_ID

# Output as JSON
python scripts/google-calendar.py calendars get primary --json

Arguments:
- calendar_id: Calendar ID or "primary" (required)
- --json: Output as JSON

events list

List calendar events.

# List upcoming events
python scripts/google-calendar.py events list

# List events in specific time range
python scripts/google-calendar.py events list \
  --time-min "2026-01-24T00:00:00Z" \
  --time-max "2026-01-31T23:59:59Z"

# List events from specific calendar
python scripts/google-calendar.py events list --calendar CALENDAR_ID

# Search events
python scripts/google-calendar.py events list --query "meeting"

# List with custom max results
python scripts/google-calendar.py events list --max-results 20

# Output as JSON
python scripts/google-calendar.py events list --json

Arguments:
- --calendar: Calendar ID (default: "primary")
- --time-min: Start time (RFC3339 timestamp, e.g., "2026-01-24T00:00:00Z")
- --time-max: End time (RFC3339 timestamp)
- --max-results: Maximum number of results (default: 10)
- --query: Free text search query
- --json: Output as JSON

Time Format Examples:
- UTC: 2026-01-24T10:00:00Z
- With timezone: 2026-01-24T10:00:00-05:00 (EST)
- Date only (all-day): 2026-01-24

events get

Get details for a specific event.

# Get event from primary calendar
python scripts/google-calendar.py events get EVENT_ID

# Get event from specific calendar
python scripts/google-calendar.py events get EVENT_ID --calendar CALENDAR_ID

# Output as JSON
python scripts/google-calendar.py events get EVENT_ID --json

Arguments:
- event_id: Event ID (required)
- --calendar: Calendar ID (default: "primary")
- --json: Output as JSON

events create

Create a new calendar event.

# Create simple event with time
python scripts/google-calendar.py events create \
  --summary "Team Meeting" \
  --start "2026-01-24T10:00:00-05:00" \
  --end "2026-01-24T11:00:00-05:00"

# Create all-day event
python scripts/google-calendar.py events create \
  --summary "Conference" \
  --start "2026-01-24" \
  --end "2026-01-25" \
  --timezone "America/New_York"

# Create event with details
python scripts/google-calendar.py events create \
  --summary "Project Review" \
  --start "2026-01-24T14:00:00Z" \
  --end "2026-01-24T15:00:00Z" \
  --description "Quarterly project review meeting" \
  --location "Conference Room A" \
  --attendees "[email protected],[email protected]"

# Create on specific calendar
python scripts/google-calendar.py events create \
  --calendar CALENDAR_ID \
  --summary "Event" \
  --start "2026-01-24T10:00:00Z" \
  --end "2026-01-24T11:00:00Z"

# Output as JSON
python scripts/google-calendar.py events create \
  --summary "Meeting" \
  --start "2026-01-24T10:00:00Z" \
  --end "2026-01-24T11:00:00Z" \
  --json

Arguments:
- --summary: Event title (required)
- --start: Start time - RFC3339 timestamp or YYYY-MM-DD for all-day (required)
- --end: End time - RFC3339 timestamp or YYYY-MM-DD for all-day (required)
- --calendar: Calendar ID (default: "primary")
- --description: Event description
- --location: Event location
- --attendees: Comma-separated list of attendee email addresses
- --timezone: Timezone for all-day events (e.g., "America/New_York")
- --json: Output as JSON

events update

Update an existing event.

# Update event summary
python scripts/google-calendar.py events update EVENT_ID \
  --summary "Updated Meeting Title"

# Update event time
python scripts/google-calendar.py events update EVENT_ID \
  --start "2026-01-24T15:00:00Z" \
  --end "2026-01-24T16:00:00Z"

# Update multiple fields
python scripts/google-calendar.py events update EVENT_ID \
  --summary "Project Sync" \
  --location "Room B" \
  --description "Updated agenda"

# Update event on specific calendar
python scripts/google-calendar.py events update EVENT_ID \
  --calendar CALENDAR_ID \
  --summary "New Title"

# Output as JSON
python scripts/google-calendar.py events update EVENT_ID \
  --summary "Meeting" \
  --json

Arguments:
- event_id: Event ID (required)
- --calendar: Calendar ID (default: "primary")
- --summary: New event title
- --start: New start time (RFC3339 or YYYY-MM-DD)
- --end: New end time (RFC3339 or YYYY-MM-DD)
- --description: New description
- --location: New location
- --json: Output as JSON

events delete

Delete a calendar event.

# Delete event from primary calendar
python scripts/google-calendar.py events delete EVENT_ID

# Delete event from specific calendar
python scripts/google-calendar.py events delete EVENT_ID --calendar CALENDAR_ID

Arguments:
- event_id: Event ID (required)
- --calendar: Calendar ID (default: "primary")
- --json: Output as JSON (for consistency, no output on success)

freebusy

Check free/busy information for calendars.

# Check availability for primary calendar
python scripts/google-calendar.py freebusy \
  --start "2026-01-24T00:00:00Z" \
  --end "2026-01-25T00:00:00Z"

# Check multiple calendars
python scripts/google-calendar.py freebusy \
  --start "2026-01-24T08:00:00Z" \
  --end "2026-01-24T17:00:00Z" \
  --calendars "primary,[email protected],[email protected]"

# Output as JSON
python scripts/google-calendar.py freebusy \
  --start "2026-01-24T00:00:00Z" \
  --end "2026-01-25T00:00:00Z" \
  --json

Arguments:
- --start: Start time (RFC3339 timestamp, required)
- --end: End time (RFC3339 timestamp, required)
- --calendars: Comma-separated calendar IDs (default: "primary")
- --json: Output as JSON

Examples

Verify Setup

python scripts/google-calendar.py check

View upcoming events

# Next 10 events
python scripts/google-calendar.py events list

# This week's events
python scripts/google-calendar.py events list \
  --time-min "2026-01-24T00:00:00Z" \
  --time-max "2026-01-31T23:59:59Z"

Create a meeting

python 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]"

Schedule an all-day event

python scripts/google-calendar.py events create \
  --summary "Company Holiday" \
  --start "2026-12-25" \
  --end "2026-12-26" \
  --timezone "America/New_York"

Reschedule an event

python scripts/google-calendar.py events update EVENT_ID \
  --start "2026-01-24T14:00:00Z" \
  --end "2026-01-24T15:00:00Z"

Find available time slots

python 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]"

Search for events

python scripts/google-calendar.py events list --query "project review"

Cancel an event

python scripts/google-calendar.py events delete EVENT_ID

Date and Time Format

Google Calendar uses RFC3339 format for timestamps. See calendar-timezones.md for detailed timezone handling.

Timed Events

Use RFC3339 format with timezone:

2026-01-24T10:00:00-05:00  # 10 AM EST
2026-01-24T10:00:00Z       # 10 AM UTC
2026-01-24T10:00:00+01:00  # 10 AM CET

All-Day Events

Use date format (YYYY-MM-DD):

2026-01-24  # All day on January 24, 2026

For all-day events, you can specify a timezone using the --timezone argument.

Troubleshooting

Check command fails

Run python scripts/google-calendar.py check to diagnose issues. It will provide specific error messages and setup instructions.

Authentication failed

1. Verify your OAuth client ID and client secret are correct in ~/.config/agent-skills/google.yaml
2. Token expired or corrupted - clear and re-authenticate:
   bash keyring del agent-skills google-calendar-token-json python scripts/google-calendar.py check

Permission denied

Your OAuth token may not have the necessary scopes. Revoke access at https://myaccount.google.com/permissions, clear your token, and re-authenticate.

Import errors

Ensure dependencies are installed:

pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Event not found

Verify the event ID and calendar ID are correct. Event IDs are unique per calendar.

Timezone issues

Always use RFC3339 format with explicit timezone offsets, or UTC (Z suffix). For all-day events, use YYYY-MM-DD format and optionally specify --timezone.

Rate limiting

Google Calendar API has quota limits. If you hit rate limits, wait a few minutes before retrying. For high-volume usage, consider requesting quota increases in the Google Cloud Console.

API Scopes

This skill requests the following OAuth scopes:

• https://www.googleapis.com/auth/calendar.readonly - Read calendar events and settings
• https://www.googleapis.com/auth/calendar.events - Create, update, and delete events

These scopes provide full calendar management capabilities while following the principle of least privilege.

Security Notes

• OAuth tokens are stored securely in your system keyring
• Client secrets are stored in ~/.config/agent-skills/google-calendar.yaml with file permissions 600
• No passwords are stored - only OAuth tokens
• Tokens refresh automatically when using the skill
• Browser-based consent ensures you approve all requested permissions

Always review OAuth consent screens before granting access to your Google Calendar.