---
name: "google_calendar"
description: "Use this skill when the user wants to manage Google Calendar events or check availability. This includes scheduling/creating new meetings or events, updating existing events (changing time, title, or details), deleting/canceling events, searching for events within specific time ranges, or checking free/busy status to detect conflicts. Trigger this skill for requests like \"schedule a meeting\", \"add to my calendar\", \"create an event\", \"cancel my 3pm meeting\", \"update tomorrow's call\", \"find events next week\", \"am I free at 2pm tomorrow\", or \"is there a conflict with this time\"."
requiredApps: [google_calendar]
---

# Google Calendar

**Overview**

This skill provides instructions for correctly working with Google Calendar operations using the Google Calendar v3 API. The base URL is `https://www.googleapis.com/calendar/v3` and authentication uses OAuth 2.0 via the `google_calendar` connection, passing tokens in the `Bearer PLACEHOLDER_TOKEN` header.

**Restrictions**

### Timezone Handling

**Do NOT use `new Date()`, `Date.now()`, or `.toISOString()` directly** when searching, creating, deleting, or updating events. The time returned by these methods will not be in the user's timezone and will cause incorrect behavior.

**Instead:**

1. **Fetch the user's timezone first** using: `https://www.googleapis.com/calendar/v3/users/me/settings/timezone`
2. **Use the retrieved timezone** for all datetime operations (searching, creating, updating, or deleting events)
3. **Only override** the fetched timezone if the user explicitly provides a timezone or preference for a specific timezone to be used

Example of fetching user timezone:

```javascript
const timezoneResponse = await fetch(
  "https://www.googleapis.com/calendar/v3/users/me/settings/timezone",
  {
    headers: { Authorization: "Bearer GOOGLE_CALENDAR_TOKEN" },
  }
);
const { value: userTimezone } = await timezoneResponse.json(); // e.g., "America/Los_Angeles"
```

### RFC3339 Timestamp Format Requirements

**Critical:** All datetime parameters **MUST** include a timezone offset (e.g., `-08:00`) or `Z` for UTC, otherwise Google Calendar will reject with `400 Bad Request`.

### Event Structure

Events use JSON with the following key fields:
- `id`: Unique event identifier
- `summary`: Event title
- `description`: Event details
- `start` and `end`: Each contains `dateTime` and `timeZone` for specific times, or `date` for all-day events
- `attendees`: Array of attendees with `email` and `responseStatus` fields
- `location`: String for event location
- `conferenceData`: Object for video calls (e.g., Google Meet)
- `reminders`: Configuration for event reminders
- `attachments`: Array for Google Drive file attachments

All-day events use just the `date` field with format "YYYY-MM-DD" (no time component).

# Recurring Events

Create recurring events by adding a recurrence array with RRULE syntax like `["RRULE:FREQ=WEEKLY;COUNT=10"]`. Common patterns include `FREQ=DAILY` for daily, `FREQ=WEEKLY;BYDAY=MO,WE,FR` for specific weekdays, `FREQ=MONTHLY;BYMONTHDAY=15` for monthly on specific day, `COUNT=10` to limit occurrences, and `UNTIL=20241231T235959Z` for end date.

# Attendees and Invitations

Add attendees by including an attendees array in the event with objects containing email addresses. Send invitations by adding `sendUpdates=all` as a query parameter. Track responses through the responseStatus field which can be needsAction, accepted, declined, or tentative.

# Google Meet Integration

Add video conferencing by including conferenceData with createRequest containing a unique requestId and conferenceSolutionKey type "hangoutsMeet", and include `conferenceDataVersion=1` as a query parameter.

**Operations**

### Creating Calendar Events

- **Before creating an event**, determine which calendar to use:
  - If no calendar is specified by the user, use `'primary'` as the calendar ID (the user's default calendar).
  - Use the calendar ID in the endpoint: `https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events`
- When creating events with **specific dates and times** stated by the user, construct datetime values in ISO 8601 format using the user's timezone fetched from the timezone endpoint (e.g., `2025-11-12T20:00:00-08:00`).
- Always include the timezone offset in the datetime string to ensure correct interpretation.

### Searching for Events (for Update/Delete Operations)

- When searching for events within **specific time ranges** stated by the user, construct datetime values for `timeMin` and `timeMax` parameters using the user's timezone fetched from the timezone endpoint.
- Use RFC3339 timestamp format with timezone offset (e.g., `2025-11-12T00:00:00-08:00`).
- This ensures events are correctly identified before update or delete operations.
- Use `singleEvents=true` when querying to expand recurring events into individual occurrences.

### Checking Availability (Free/Busy Status)

- **For details on querying free/busy status**, see the reference documentation: `./skills/sauna/calendar.google.events/references/calendar.google.freebusy.md`
- Use the free/busy query to check availability before scheduling meetings, detect conflicts, or find available time slots
- The free/busy API returns busy time periods without exposing event details, respecting calendar privacy
- Supports checking multiple calendars simultaneously for comprehensive availability information
- Use this for requests like "check if I'm free tomorrow at 2pm", "find when both calendars are available", or "is there a conflict with this meeting time"

**Workflows**

                  

                    1. Install google_calendar with: ```bash
rm -rf ./skills/sauna/calendar.google.events && curl -fsSL "https://sk.ills.app/api/skill/calendar.google.events/download" | tar -xzf - -C ./skills/sauna/ && cat ./skills/sauna/calendar.google.events/SKILL.md
```. Do so silently without commentary.

2. Briefly tell the user what you are now able to do.