google-calendar-skill

name	google-calendar-skill
description	Manage Google Calendar - search, create, update events and answer calendar questions. Use when user wants to interact with their Google Calendar for scheduling and calendar operations.

Google Calendar Skill

This skill provides comprehensive Google Calendar integration through lightweight CLI scripts. All operations are token-efficient and composable.

First-Time Setup

Before using this skill, you must set up OAuth authentication:

1. Install dependencies:

   cd ~/.claude/skills/google-calendar-skill && npm install
   

2. Set up Google Cloud credentials:

   • Follow the guide in docs/google-cloud-setup.md
   • Enable Google Calendar API
   • Download credentials.json and save to scripts/auth/credentials.json

3. Authenticate:

   cd ~/.claude/skills/google-calendar-skill && npm run setup
   

This will open a browser for Google OAuth and save your token locally.

Multi-Account Support

The Calendar skill supports multiple accounts (e.g., personal and work calendars):

Add Additional Accounts

# Add a second account (from skill directory)
npm run setup -- --account work

# Add a third account
npm run setup -- --account personal

Each account needs separate OAuth authentication.

Manage Accounts

# List all configured accounts
node scripts/manage-accounts.js --list

# Set default account (used when --account is not specified)
node scripts/manage-accounts.js --set-default work

# Remove an account
node scripts/manage-accounts.js --remove old-account

Using Specific Accounts

All Calendar operations support the --account parameter:

# List work calendar events
node calendar-events-list.js --account work --limit 10

# Create event on personal calendar (or omit --account to use default)
node calendar-events-create.js --account personal --summary "..." --start "..." --end "..."

# Search work calendar
node calendar-events-list.js --account work --query "team meeting"

If --account is not specified, the default account is used.

Usage Guidelines

1. Read Documentation On-Demand

When first using Calendar operations, read the comprehensive README:

cat ~/.claude/skills/google-calendar-skill/README.md

This provides detailed usage examples for all operations.

2. Execute Scripts via Bash

All scripts are in the scripts/ directory and output JSON for easy parsing:

cd ~/.claude/skills/google-calendar-skill/scripts

3. Parse JSON Output

All scripts return JSON. Parse the output and present relevant information to the user in a friendly format.

4. Chain Operations

Save intermediate results to files when chaining operations:

# List events and save
node calendar-events-list.js --query "team meeting" > /tmp/events.json

# Get details for first event
EVENT_ID=$(cat /tmp/events.json | jq -r '.events[0].id')
node calendar-events-get.js --id "$EVENT_ID"

Available Operations

List Calendars

node calendar-list.js

Search/List Events

# Upcoming events
node calendar-events-list.js --limit 10

# Search by date range
node calendar-events-list.js \
  --timeMin "2025-11-15T00:00:00Z" \
  --timeMax "2025-11-30T23:59:59Z"

# Search by keyword
node calendar-events-list.js --query "team meeting"

Get Event Details

node calendar-events-get.js --id "EVENT_ID"

Create Event

# Timed event
node calendar-events-create.js \
  --summary "Team Meeting" \
  --start "2025-11-20T14:00:00-08:00" \
  --end "2025-11-20T15:00:00-08:00" \
  --location "Conference Room A" \
  --attendees "[e-mail],[e-mail]"

# All-day event
node calendar-events-create.js \
  --summary "Company Holiday" \
  --allDay \
  --date "2025-12-25"

# With Google Meet
node calendar-events-create.js \
  --summary "Team Sync" \
  --start "2025-11-20T14:00:00-08:00" \
  --end "2025-11-20T15:00:00-08:00" \
  --addMeet

Update Event

# Update title
node calendar-events-update.js --id "EVENT_ID" --summary "New Title"

# Update time
node calendar-events-update.js \
  --id "EVENT_ID" \
  --start "2025-11-20T15:00:00-08:00" \
  --end "2025-11-20T16:00:00-08:00"

# Add attendees (preserves existing)
node calendar-events-update.js --id "EVENT_ID" --addAttendees "[e-mail]"

Delete Event

node calendar-events-delete.js --id "EVENT_ID"

Quick Add (Natural Language)

node calendar-events-quick.js --text "Lunch with Sarah tomorrow at 12pm"

Common Use Cases

Answering Calendar Questions

When users ask about their schedule:

1. Use calendar-events-list.js with appropriate time filters
2. Parse the JSON output
3. Present a natural language summary

Example:

# User asks: "What's on my calendar today?"
TODAY_START=$(date -u +"%Y-%m-%dT00:00:00Z")
TODAY_END=$(date -u +"%Y-%m-%dT23:59:59Z")
node calendar-events-list.js --timeMin "$TODAY_START" --timeMax "$TODAY_END"

Creating Events from Natural Language

For simple event creation, use quick add:

# User says: "Schedule lunch with Bob tomorrow at noon"
node calendar-events-quick.js --text "Lunch with Bob tomorrow at 12pm"

For detailed events with specific requirements, use create:

node calendar-events-create.js \
  --summary "Lunch with Bob" \
  --start "2025-11-16T12:00:00-08:00" \
  --end "2025-11-16T13:00:00-08:00" \
  --location "Restaurant Name"

Modifying Events

1. Search for the event by summary or time
2. Extract the event ID from results
3. Use update script with specific changes

# Find event
node calendar-events-list.js --query "team meeting" > /tmp/results.json
EVENT_ID=$(cat /tmp/results.json | jq -r '.events[0].id')

# Update it
node calendar-events-update.js --id "$EVENT_ID" --location "New Location"

Time Zones and Date Formats

ISO 8601 DateTime Format

Use for --start and --end with timed events:

2025-11-20T14:00:00-08:00  (2pm Pacific)
2025-11-20T14:00:00-05:00  (2pm Eastern)
2025-11-20T14:00:00Z       (2pm UTC)

Date-Only Format

Use for --date with all-day events:

2025-11-20  (YYYY-MM-DD)

Setting Timezone

# Default is America/Los_Angeles
node calendar-events-create.js --summary "..." --start "..." --end "..."

# Custom timezone
node calendar-events-create.js \
  --summary "..." \
  --start "..." \
  --end "..." \
  --timezone "America/New_York"

Error Handling

If scripts fail:

• Check that token.json exists in scripts/auth/
• If token is expired, run npm run setup again
• Verify the user granted Google Calendar API permissions
• Ensure date/time formats are valid ISO 8601
• Check that event IDs are correct

Common error patterns:

{
  "success": false,
  "error": "Token not found. Run: npm run setup"
}

Best Practices

1. Always change to the scripts directory first to ensure relative paths work
2. Parse JSON output and present user-friendly summaries
3. Validate date/time formats before passing to scripts
4. Handle timezones explicitly when creating/updating events
5. Use natural language quickAdd for simple events
6. Use structured create for events with specific requirements
7. Extract event IDs from list/search results when updating or deleting
8. Present calendar data clearly with dates, times, and attendee information

Token Efficiency

This skill is designed for minimal token usage:

• Documentation loaded only when needed
• Scripts are small and focused
• JSON output is compact and parseable
• No persistent server overhead
• ~300-500 tokens vs 13,000+ for MCP-based solutions