jeffvincent/google-calendar-skill

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

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

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