playbooks

home / skills / idanbeck / claude-skills / gcal-skill

gcal-skill skill

/gcal-skill

This skill helps you view, manage, and schedule Google Calendar events across multiple accounts with confirmation safeguards.

npx playbooks add skill idanbeck/claude-skills --skill gcal-skill

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
4.3 KB
---
name: gcal-skill
description: Read, create, and manage Google Calendar events. Use when the user asks to check calendar, view schedule, find meetings, create events, or see what's on the agenda. Supports multiple accounts.
allowed-tools: Bash, Read
---

# Google Calendar Skill - Calendar & Events

Read, create, and manage Google Calendar events. View agenda, create meetings, check availability.

## CRITICAL: Event Creation Confirmation Required

**Before creating ANY calendar event, you MUST get explicit user confirmation.**

When the user asks to create an event:
1. First, show them the complete event details:
   - Title
   - Start time
   - End time
   - Location (if any)
   - Attendees (if any)
2. Ask: "Do you want me to create this event?"
3. ONLY run the create command AFTER the user explicitly confirms

## First-Time Setup

This skill reuses credentials from gmail-skill if available. Otherwise:

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Enable **Google Calendar API** (APIs & Services -> Library)
3. Use existing OAuth client or create new Desktop app client
4. Download JSON -> save as `~/.claude/skills/gcal-skill/credentials.json`

Then just run any command - browser opens for auth.

## Commands

### Today's Events

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py today [--account EMAIL]
```

### This Week's Events

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py week [--account EMAIL]
```

### Agenda (N days)

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py agenda --days 14 [--account EMAIL]
```

### Get Event Details

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py event EVENT_ID [--account EMAIL]
```

### Create Event (Requires Confirmation)

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py create \
  --title "Meeting with John" \
  --start "2026-01-20 14:00" \
  --end "2026-01-20 15:00" \
  --location "Zoom" \
  --attendees "[email protected],[email protected]" \
  [--account EMAIL]
```

**Required arguments:**
- `--title` / `-t` - Event title
- `--start` / `-s` - Start time (various formats supported)

**Optional arguments:**
- `--end` / `-e` - End time (defaults to 1 hour after start)
- `--location` / `-l` - Event location
- `--description` / `-d` - Event description
- `--attendees` - Comma-separated attendee emails
- `--account` / `-a` - Calendar account

**Time formats supported:**
- `2026-01-20 14:00`
- `2026-01-20 2:00 PM`
- `14:00` (today at that time)
- `2:00 PM` (today at that time)

### Delete Event

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py delete EVENT_ID [--account EMAIL]
```

### Search Events

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py search "query" [--max-results N] [--account EMAIL]
```

### List Calendars

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py calendars [--account EMAIL]
```

### Manage Accounts

```bash
# List authenticated accounts
python3 ~/.claude/skills/gcal-skill/gcal_skill.py accounts

# Remove an account
python3 ~/.claude/skills/gcal-skill/gcal_skill.py logout --account EMAIL
```

## Multi-Account Support

Add accounts by using `--account` with a new email:

```bash
# First account (auto-authenticates)
python3 ~/.claude/skills/gcal-skill/gcal_skill.py today

# Add work account
python3 ~/.claude/skills/gcal-skill/gcal_skill.py today --account [email protected]

# Use specific account
python3 ~/.claude/skills/gcal-skill/gcal_skill.py week --account [email protected]
```

## Examples

### Check what's on today

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py today
```

### Look at the week ahead

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py week
```

### Find all meetings with "standup"

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py search "standup"
```

### Schedule a meeting

```bash
python3 ~/.claude/skills/gcal-skill/gcal_skill.py create \
  --title "1:1 with Sarah" \
  --start "2026-01-21 10:00" \
  --end "2026-01-21 10:30"
```

## Output

All commands output JSON for easy parsing.

## Requirements

- Python 3.9+
- `pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client requests`

## Security Notes

- Tokens stored locally in `~/.claude/skills/gcal-skill/tokens/`
- Revoke access anytime: https://myaccount.google.com/permissions
- Event creation always requires user confirmation

Overview

This skill connects to Google Calendar to read, create, and manage events across multiple accounts. It helps you check your agenda, find meetings, view day/week schedules, and create or delete events while returning structured JSON for easy parsing. Event creation always requires explicit user confirmation.

How this skill works

The skill talks to the Google Calendar API using stored OAuth credentials and local tokens. It can list today’s events, show a multi-day agenda, search events, get event details, create events (after confirmation), delete events, and list calendars or authenticated accounts. Commands accept an --account flag to target different Google accounts and output JSON for programmatic consumption.

When to use it

  • Check what’s on your calendar today or this week
  • Find meetings matching keywords or a specific time range
  • Create a new meeting, ensuring you confirm details before creation
  • Remove an event or get full event details
  • Manage or switch between multiple authenticated Google accounts

Best practices

  • Always review the full event preview before confirming creation — title, start/end, location, attendees.
  • Specify the --account flag when working with multiple calendars to avoid ambiguity.
  • Provide end time or let the skill default to a one-hour event to prevent accidental all-day events.
  • Use clear attendee emails separated by commas when creating events to ensure invitations are sent.
  • Keep credentials.json and tokens in the recommended local paths and revoke access via Google permissions if needed.

Example use cases

  • “What’s on my calendar today?” — returns today’s events in JSON for display or automation.
  • “Find meetings with ‘standup’” — searches calendar items and returns matches with IDs and times.
  • Schedule a 30-minute 1:1: preview the title, time, attendees, ask for confirmation, then create on approval.
  • List authenticated accounts or add a work account by running a command with --account.
  • Delete an event by ID when you need to remove a cancelled meeting.

FAQ

Do you automatically create events when I ask to schedule something?

No. The skill always shows the complete event details and asks “Do you want me to create this event?” It will only create the event after you explicitly confirm.

How do I use multiple Google accounts?

Include the --account EMAIL flag with commands to target a specific authenticated account. Add a new account by running any command with --account; it will prompt for OAuth if needed.