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.
version: 1.0.0
allowed-tools: [Bash, Read, Write]
---

# 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:**
   ```bash
   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:**
   ```bash
   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

```bash
# 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

```bash
# 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:

```bash
# 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:
```bash
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:

```bash
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:

```bash
# 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
```bash
node calendar-list.js
```

### Search/List Events
```bash
# 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
```bash
node calendar-events-get.js --id "EVENT_ID"
```

### Create Event
```bash
# 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 "alice@example.com,bob@example.com"

# 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
```bash
# 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 "new@example.com"
```

### Delete Event
```bash
node calendar-events-delete.js --id "EVENT_ID"
```

### Quick Add (Natural Language)
```bash
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:
```bash
# 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:
```bash
# 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:
```bash
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

```bash
# 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
```bash
# 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:
```json
{
  "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