---
name: gcal
description: Google Calendar read access — agenda, events, schedule. Use when asked about calendar, meetings, schedule, or what's on today/tomorrow.
allowed-tools:
  - Bash
  - Read
---

# Google Calendar Skill

Access Google Calendar via Python API. Uses OAuth credentials at `~/.gmail-mcp/`.

## Quick Commands

```bash
GCAL_PY=~/.claude/mcp/gmail/venv/bin/python
SCRIPTS=~/.claude/skills/gcal/scripts

# Today's agenda
$GCAL_PY $SCRIPTS/agenda.py today

# Tomorrow's agenda
$GCAL_PY $SCRIPTS/agenda.py tomorrow

# This week (7 days)
$GCAL_PY $SCRIPTS/agenda.py week

# Next event only
$GCAL_PY $SCRIPTS/next_event.py
```

## Script Reference

| Script | Purpose | Args |
|--------|---------|------|
| `agenda.py` | List events for time range | `today`, `tomorrow`, `week` |
| `next_event.py` | Next upcoming event | none |

## Request Routing

| User Request | Script | Args |
|--------------|--------|------|
| "What's on today?" | `agenda.py` | `today` |
| "Tomorrow's schedule" | `agenda.py` | `tomorrow` |
| "This week" | `agenda.py` | `week` |
| "Next meeting" | `next_event.py` | none |
| "Am I free at 3pm?" | `agenda.py` | `today` (then analyze) |

### Smart Default (no args)

- Before 6pm → today
- After 6pm → tomorrow

## Delegation Helper (Advanced)

For LLM-assisted operations:

```bash
GCAL_PY=~/.claude/mcp/gmail/venv/bin/python
HELPER=~/.claude/mcp/delegation/gcal_delegate.py

# Haiku tier - fetch and format
$GCAL_PY $HELPER today

# Sonnet tier - analyze (spawns claude --model sonnet)
$GCAL_PY $HELPER summary
```

## Output Format

```
📅 Today — Thursday, Jan 2

  9:00 AM   Team standup (30m)
            📍 Zoom · 👥 5 attendees

 10:30 AM   1:1 with Sarah (45m)
            📍 Conference Room B

No more events today.
```

### Context Fields

- 📍 Location or meeting link
- 👥 Attendee count
- 📝 Description snippet (if relevant)

## Error Handling

### Missing Calendar Scope

```
Calendar access not authorized. To fix:
1. Delete cached token: rm ~/.gmail-mcp/token.json
2. Run /gcal today to re-authenticate with Calendar scope
```

## Policy

- **Read-only** operations only
- Show **context** (attendees, location) by default
- **Summarize** results, don't dump raw data
- Start with **lowest capable** model tier