| name | gmail |
| description | Search and read Gmail emails using the Gmail API. Use for research, finding information in email, reading threads, or summarizing conversations. Triggers on: search my email, search gmail, find emails about, read this email, check my inbox, look up emails from, what did X send me, gmail search. |
Search and read Gmail for research or information retrieval.
Setup Check
Before running, verify credentials exist:
ls ~/.claude/gmail/credentials.json
If missing, tell the user:
"You need to set up Gmail API credentials first. See the setup instructions below."
Setup (one-time):
- Go to console.cloud.google.com
- Create a project → Enable Gmail API
- Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
- Application type: Desktop app
- Download the JSON → save as
~/.claude/gmail/credentials.json
- Run
/gmail again — it will open your browser to authorize (one-time)
Parsing Arguments
Parse $ARGUMENTS for the user's intent:
- Natural language queries like "emails from stripe last month" → convert to Gmail search syntax
- Explicit queries with Gmail operators (from:, subject:, after:, etc.) → use as-is
--limit N → max results, default 10--body → include full body in search results (slower, use only when user wants content)--thread → fetch full thread instead of individual message
Gmail Search Query Conversion
Convert natural language to Gmail search syntax:
- "from stripe last week" →
from:stripe after:2026/03/14
- "unread newsletters" →
is:unread label:newsletters
- "emails about invoice" →
subject:invoice OR invoice
- "attachments from john" →
from:john has:attachment
- "today's emails" →
after:2026/03/21
Today's date: 2026-03-21
Flow
Step 1: Search
python3 ~/.claude/skills/gmail/gmail_client.py search "<query>" --limit <N> [--body]
On first run, this opens the browser for OAuth authorization. Tell the user to complete that step, then re-run.
Step 2: Present Results
Show a clean table of results:
Step 3: Read Full Email (if user wants details)
When user wants to read a specific email:
python3 ~/.claude/skills/gmail/gmail_client.py read <message_id>
Or fetch the full thread:
python3 ~/.claude/skills/gmail/gmail_client.py thread <thread_id>
Step 4: Analyze / Summarize
After reading emails, synthesize the content for the user's research goal. Focus on:
- Key information, decisions, or action items
- Chronological summaries for threads
- Patterns across multiple emails (e.g., "All 5 emails from Stripe are receipts for X")
Rules
- Never store or log email content to disk unless the user explicitly asks
- If a query returns 0 results, suggest alternative search terms
- Respect the
--limit — don't fetch more than requested
- For research tasks, use
--body only when the snippet isn't enough
- When summarizing threads, preserve chronological order
- If the user asks to "find all emails from X", default limit to 20 and ask if they want more
