---
name: gcal
description: Google Calendar read access — agenda overview, event details, smart summaries
allowed-tools:
  - Bash
---

# Google Calendar Skill

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

## Command Routing

### 1. Exact Subcommand Match (priority)

| Input | Action |
|-------|--------|
| `today` | Today's agenda |
| `tomorrow` | Tomorrow's agenda |
| `week` | Next 7 days, grouped by day |
| `next` | Next upcoming event only |
| `summary` | Sonnet-powered week analysis |

### 2. Natural Language Fallback

| Input | Routes To |
|-------|-----------|
| "what's on today", "today's meetings" | today |
| "this week", "next 7 days" | week |
| "next meeting", "what's next" | next |
| "am I busy tomorrow", "tomorrow's schedule" | tomorrow |
| "overview", "summarize my week" | summary |

### 3. Smart Default (no args)

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

### 4. Ambiguous Input

Ask for clarification rather than guess.

## Delegated Operations

Use the delegation helper for cost-efficient 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
$GCAL_PY $HELPER tomorrow
$GCAL_PY $HELPER week
$GCAL_PY $HELPER next

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

## Delegation Tiers

| Subcommand | Tier | Reason |
|------------|------|--------|
| today, tomorrow, week, next | Haiku | Fetch + format only |
| summary | Sonnet | Requires understanding/analysis |

## Output Format

The helper returns JSON. Format for user as:

### Simple List (today/tomorrow/next)

```
📅 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.
```

### Grouped by Day (week)

```
📅 This Week — Jan 2-8

━━━ Thursday, Jan 2 ━━━
  9:00 AM   Team standup (30m)
  2:00 PM   Project review (1h)

━━━ Friday, Jan 3 ━━━
  11:00 AM  Client call (1h)
```

### Context Fields (show when available)

- 📍 Location or meeting link
- 👥 Attendee count
- 📝 Description snippet (first ~50 chars)

## Error Handling

### Missing Calendar Scope

If helper reports scope error:

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

### No Events

```
📅 Today — Thursday, Jan 2

No events scheduled.
```

## Policy

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