---
name: Google Calendar
slug: google-calendar-2
category: Automation
description: Google Calendar lets an agent view, create, and manage events and check availability across connected Google accounts. Use it to schedule meetings, find free slots, and respond to invitations.
github: "https://github.com/vellum-ai/vellum-assistant/tree/main/skills/google-calendar"
language: TypeScript
stars: 1095
forks: 160
install: "npx degit https://github.com/vellum-ai/vellum-assistant/tree/main/skills/google-calendar ~/.claude/skills/google-calendar"
installs_to: ~/.claude/skills/google-calendar
source_path: skills/google-calendar/SKILL.md
collection_size: 25
category_size: 1523
collection_url: "https://dirskills.com/collections/vellum-ai/vellum-assistant"
added: 2026-08-20T07:56:36.869Z
last_synced: 2026-08-20T07:56:36.869Z
canonical_url: "https://dirskills.com/skills/google-calendar-2"
---

# Google Calendar

Google Calendar lets an agent view, create, and manage events and check availability across connected Google accounts. Use it to schedule meetings, find free slots, and respond to invitations.

**Install:**

```bash
npx degit https://github.com/vellum-ai/vellum-assistant/tree/main/skills/google-calendar ~/.claude/skills/google-calendar
```

## README

## Script Reference

All operations use a single CLI script that returns JSON:

- **Success**: `{ "ok": true, "data": ... }`
- **Failure**: `{ "ok": false, "error": "..." }`

| Script            | Subcommand     | Description                                                    |
| ----------------- | -------------- | -------------------------------------------------------------- |
| `scripts/gcal.ts` | `list`         | List events within a date range                                |
| `scripts/gcal.ts` | `get`          | Get full details of a specific event                           |
| `scripts/gcal.ts` | `create`       | Create a new event (**requires user confirmation**)            |
| `scripts/gcal.ts` | `availability` | Check free/busy times across calendars                         |
| `scripts/gcal.ts` | `rsvp`         | Respond to an event invitation (accepted, declined, tentative) |

## Usage Examples

```bash
# List events in a date range
bun scripts/gcal.ts list --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-22T00:00:00Z"

# Get full details of a specific event
bun scripts/gcal.ts get --event-id "abc123"

# Create a new event (gates on assistant ui confirm)
bun scripts/gcal.ts create --summary "Team Meeting" --start "2024-01-15T09:00:00-05:00" --end "2024-01-15T10:00:00-05:00" --timezone "America/New_York"

# Check availability for a day
bun scripts/gcal.ts availability --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-15T23:59:59Z"

# RSVP to an event invitation
bun scripts/gcal.ts rsvp --event-id "abc123" --response accepted

# Target a specific connected account (see "Multiple Accounts" below)
bun scripts/gcal.ts list --time-min "2024-01-15T00:00:00Z" --time-max "2024-01-22T00:00:00Z" --account "work@example.com"
```

Every subcommand accepts `--account <email>` to select which connected Google account the request runs against. When omitted, the request runs against a single account chosen automatically — safe only when exactly one Google account is connected. Each JSON envelope echoes the queried account in an `account` field when it is reported by the OAuth layer, so an empty result is self-describing (e.g. `No events found in the specified time range for work@example.com.`).

## Connection Setup

1. **Check connection health first.** Run `assistant oauth status google`. This checks whether the user's Google account is connected and the token is valid. Google Calendar shares the same OAuth connection as Gmail — if the user already connected Gmail, calendar access is included.
   - **If the status output shows more than one active connection, you MUST pass `--account <email>` on every `scripts/gcal.ts` invocation**, matching the calendar the user is asking about. When the user references a calendar by name or company (e.g. "my Acme calendar"), map it to the connected account email before querying. **Omitting `--account` with multiple connections silently queries one arbitrary account** — an empty or partial result then looks like a genuinely free calendar when it is really the wrong account. Confirm the `account` field in each response matches the account you intended.
2. **If no connection is found or the status check fails:** Load the `vellum-oauth-integrations` skill. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.

## Scheduling Playbook

When the user wants to schedule something:

1. **Always check availability first** before proposing times. Use `bun scripts/gcal.ts availability` to find free slots.
2. Propose 2-3 available time options to the user.
3. Once the user picks a time, create the event with `bun scripts/gcal.ts create`.
4. If adding other attendees, mention that they'll receive an invitation email.

## Date & Time Handling

- Use ISO 8601 format for dates and times (e.g., `2024-01-15T09:00:00-05:00`).
- For all-day events, use date-only format (e.g., `2024-01-15`).
- Always ask the user for their timezone if it's not already known from context or their profile.
- When listing events, display times in the user's local timezone.

## Confidence & Safety

Create and RSVP are **medium-risk** operations:

- **Create**: The `create` subcommand gates on `assistant ui confirm` — it presents a confirmation dialog to the user and only proceeds if approved. Pass `--skip-confirm` when the user has already given explicit confirmation in the conversation.
- **RSVP**: The `rsvp` subcommand gates on `assistant ui confirm` — it presents a confirmation dialog showing the event, current status, and new response. Pass `--skip-confirm` when the user has already given explicit confirmation in the conversation.

Confidence scores for medium-risk operations:

- **0.9-1.0**: User explicitly requested this exact action
- **0.7-0.8**: Action is strongly implied by context
- **0.5-0.6**: Reasonable inference but some ambiguity
- **Below 0.5**: Ask the user to confirm before proceeding

## Error Recovery

When a calendar script fails with a token or authorization error:

1. **Try to reconnect silently.** Run `assistant oauth ping google`. This often resolves expired tokens automatically.
2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Google Calendar needs to be reconnected - let me set that up") and immediately load the `vellum-oauth-integrations` skill. The user came to you to get something done, not to troubleshoot - make it seamless.
3. **Never try alternative approaches.** Don't use curl, browser automation, or any workaround. If the scripts can't do it, the reconnection flow is the answer.
4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.