---
name: gmail
description: Gmail read access via Python API - search, check unread, detect urgent emails. Use when user asks about email, inbox, or messages.
allowed-tools:
  - Bash
---

# Gmail Skill

Access Gmail via Python API calls. Uses OAuth credentials at `~/.gmail-mcp/`.

## Quick Commands

Run scripts using the gmail venv:

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

# Check unread (last 7 days, grouped by sender)
$GMAIL_PY $SCRIPTS/check_unread.py 7

# Check urgent emails
$GMAIL_PY $SCRIPTS/check_urgent.py

# Search with custom query
$GMAIL_PY $SCRIPTS/search.py "from:github.com" 10
```

## Script Reference

| Script | Purpose | Args |
|--------|---------|------|
| `check_unread.py` | List unread, grouped by sender | `[days] [max]` |
| `check_urgent.py` | Find urgent/important emails | none |
| `search.py` | Custom query search | `<query> [max]` |

## Request Routing

| User Request | Script | Tier |
|--------------|--------|------|
| "Check my email" | `check_unread.py` | Haiku |
| "How many unread?" | `check_unread.py` | Haiku |
| "Any urgent emails?" | `check_urgent.py` | Haiku |
| "Search for X" | `search.py "X"` | Haiku |
| "Summarize my inbox" | Run script + analyze | Sonnet |
| "What should I prioritize?" | Run script + reason | Opus |

## Query Patterns

For custom searches, see [references/query-patterns.md](references/query-patterns.md).

Common queries:
- `is:unread newer_than:7d` - Unread last week
- `from:github.com` - GitHub notifications
- `has:attachment larger:5M` - Large attachments
- `subject:urgent is:unread` - Urgent unread

## Delegation Helper (Advanced)

For LLM-assisted operations (summarization, triage):

```bash
GMAIL_PY=~/.claude/mcp/gmail/venv/bin/python
HELPER=~/.claude/mcp/delegation/gmail_delegate.py

# Summarize emails (spawns claude --model sonnet)
$GMAIL_PY $HELPER summarize --query "from:github.com"

# Triage urgent (spawns claude --model sonnet)
$GMAIL_PY $HELPER urgent
```

## Model Selection

| Model | Use For |
|-------|---------|
| **Haiku** | Fetch, count, list, simple search |
| **Sonnet** | Summarize, categorize, extract |
| **Opus** | Prioritize, analyze, cross-reference |

## Policy

- **Read-only** operations only
- **Summarize** results (don't dump raw content)
- Report **metadata**, not full body unless asked
- Start with **lowest capable** model tier