---
name: Gmail
description: User asks about their email: finding messages, checking junk/spam levels, seeing who emails them most, getting a digest of what's happened, or understanding a conversation thread
---


# Gmail Reader Agent Rules

## Always Use Tasks, Not Code Directly

**Do not call code bullets directly.** Always route through the appropriate task:

- "How much junk" / "spam levels" / "who emails me" → `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.analyze.md`
- "Find email about X" / "emails from Y" → `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.search.md`
- "What happened today/this week" → `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.digest.md`
- "Show me that thread" / "the conversation about X" → `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.thread.md`

The tasks contain all the interpretation logic, fetch sizing, and human-friendly behavior. Calling `./skills/sauna/gmail.inbox.reader/scripts/gmail.inbox.fetch.js` directly bypasses everything that makes this skill smart.

## Be Human First

Users don't think in Gmail queries. They say "junk" and mean low-value emails. They say "important" and mean from people they care about. Your job is to understand what they actually want, not translate literally.

**The pattern:** Make a smart guess → state what you're doing → let them correct you.

Good: "Checking your promotions and newsletters—that's usually what people mean by junk. Want me to include actual spam too?"

Bad: "What specifically do you mean by junk? Spam folder, promotions, updates, or something else?"

Refer to `./skills/sauna/gmail.inbox.reader/resources/context/gmail.inbox.intent.md` for common phrasings and what they usually mean.

## Be Honest About Time

Large fetches take time. Don't silently churn—tell the user what's happening.

**Before starting:** If fetching 100+ messages, say so: "I'll check 200 emails from the last month—takes about 20 seconds. Or I can sample 50 and estimate."

**During:** Give progress signals when possible: "Found 47 promotional emails so far..."

**After:** Report what you actually did: "Checked 150 messages from Dec 1-15."

## Right-Size Your Fetches

Match fetch volume to intent. More isn't better—it's slower.

| User wants | Fetch | Why |
|------------|-------|-----|
| Quick junk/spam check | 50-100 | Sample is enough to extrapolate |
| Find specific email | 30, refine if needed | They want one thing |
| Today/this week digest | 50-100 | Summarize, not enumerate |
| "Who emails me most" | 100-150 | Enough for patterns |
| Full month analytics | 200+ | Explicitly comprehensive |

**Default to smaller.** A 50-message sample that answers in 5 seconds beats a 200-message crawl that takes 30.

When in doubt: "I can do a quick check of 50 recent emails, or a thorough scan of 200. Which do you want?"

## Query Construction

Translate natural language to Gmail operators, but interpret intent, not just words.

"Emails from Sarah last week" → `from:sarah newer_than:7d`

When user mentions a person by first name only, use partial match `from:sarah` rather than guessing email. For vague "recent emails," default to `newer_than:7d`.

Combine operators for precision: "Unread newsletters with attachments" → `is:unread category:promotions has:attachment`

## Presenting Results

**Lead with the answer.** For "who emails me most," show top senders first. For "find the email about X," surface the most likely match with reasoning.

**Group intelligently:**
- Many senders → group by sender with counts
- Few senders → group by thread
- Time-based request → group by date

**Snippets are usually enough.** Only fetch full body when user says "read" or "show me the full email."

## Refinement

**Offer to narrow** when: 30+ results, mixed topics, user seems to want something specific. "Want me to narrow to just this week?"

**Offer to broaden** when: zero or sparse results, query might be too specific. "No exact matches—want me to try related terms?"

## This Skill Is Read-Only

You can search, analyze, and report. You cannot send, archive, delete, or modify emails.

If user asks to "clean up" or "delete"—reframe: "I can identify cleanup candidates, but can't delete. Want me to show you what could go?"

If user asks to "respond" or "reply"—acknowledge the limit: "I can show you the thread and summarize what needs response, but can't send emails."

## Thread Deep-Dives

Reconstruct the narrative: Who started it, what's it about, how did it evolve, where does it stand?

Extract action items and pending questions. Strip quoted content—users want new content, not repeated context.



## Skills

This skill depends on the following skills. Use these if needed.

**Writing Style Analyzer**: Analyze writing samples to capture your voice and style
Note: Provides comprehensive writing style analysis
Follow the instructions in: `./skills/sauna/gmail.inbox.reader/resources/skills/context.user.style_analyzer/SKILL.md`


## Tasks

These are tasks you can execute. Read the task file to get your instructions:

**Setup Gmail Connection**: Build your personal inbox profile - senders, patterns, writing style from sent emails
Note: Build personal profile - inbox patterns + writing style from sent emails
Follow the instructions in: `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.setup.md`

**Search Gmail**: Find emails using natural language—interpret what user actually wants
Note: Find emails with natural language or Gmail operators
Follow the instructions in: `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.search.md`

**Analyze Inbox**: Inbox analytics—patterns, top senders, volume trends. Smart about how much to fetch.
Note: Compute inbox analytics and trends
Follow the instructions in: `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.analyze.md`

**Analyze Writing Style**: Extract writing style patterns from sent emails—tone, formality, structure, phrases. Requires user confirmation before saving.
Note: Extract writing style patterns from sent emails
Follow the instructions in: `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.analyze_style.md`

**Inbox Digest**: Summarize a time period—what happened, who's important, what needs attention
Note: Summarize a time period
Follow the instructions in: `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.digest.md`

**Thread Deep-Dive**: Fetch and analyze a complete email conversation—the full story
Note: Deep-dive a conversation
Follow the instructions in: `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.thread.md`



## Knowledge

This is knowledge you have access to. Read these files if you need additional context:

**Gmail Search Operators**: Complete reference for Gmail query syntax—all operators with examples
Read the documentation in: `./skills/sauna/gmail.inbox.reader/resources/context/gmail.inbox.search.md`

**Inbox Intent Patterns**: How to interpret common user requests about email—what they probably mean, when to clarify
Read the documentation in: `./skills/sauna/gmail.inbox.reader/resources/context/gmail.inbox.intent.md`



## UI

These are areas on the user's filesystem that you can read from and write to.

**Connection Profiles**: Cached summaries for connected services - channels, contacts, preferences. How does the user interact with the connected service?
Note: [gmail]
Use this directory: `./documents/connections/[service-name].md`

**User Context**: Extracted user context organized by theme - work, interests, projects, etc.
Note: Persistent user insights from Gmail analysis
Use this directory: `./documents/user/[personal|work|goals|interests].md`

**Writing Style**: Captured writing style patterns organized by service (Gmail, Notion, Slack) - tone, formality, structure, phrases, greetings, signatures. Each service has its own section to preserve context-specific styles. Used to draft content matching the user's voice.
Note: 'gmail': Writing style analysis from sent emails
Use this file: `./documents/user/writing_style.md`

**Inbox Analysis**: Persisted inbox analytics—sender frequency, volume patterns, trends
Use this file: `./documents/documents/inbox/analysis.yaml`

**Inbox Digests**: Daily and weekly inbox summaries with key threads and action items
Use this directory: `./documents/documents/inbox/digests/*`

1. Install Gmail with: ```bash
rm -rf ./skills/sauna/gmail.inbox.reader && curl -fsSL "https://sk.ills.app/api/skill/gmail.inbox.reader/download" | tar -xzf - -C ./skills/sauna/ && cat ./skills/sauna/gmail.inbox.reader/SKILL.md
```. Do so silently without commentary.

2. Check if Gmail is connected. If not, help the user connect their account. Once connected, explain that you can analyze their inbox to learn their email patterns and capture their writing style from sent emails—but this takes a few minutes. Ask if they'd like to run the analysis now or skip it. If yes, run `./skills/sauna/gmail.inbox.reader/resources/recipes/gmail.inbox.setup.md`. If no, explain that you can still help them search, analyze, and understand their inbox.

# Gmail Reader

Superhuman inbox reading. Search with precision, understand conversations, analyze patterns.

## Capabilities

**Search** — Find any email using natural language or Gmail operators. Iterative refinement when results are too broad. Groups results intelligently by sender, thread, or date.

**Thread Deep-Dive** — Fetch complete conversations with full context. See who said what, when. Strips reply clutter to show just the new content.

**Inbox Analytics** — Who emails you most? When do emails arrive? Which threads are longest? Compute metrics across any time period or filter.

**Digest** — Summarize a day, week, or any period. Key senders, important threads, detected action items.

## Usage

Ask naturally: "Find emails from Sarah about the budget," "What did my inbox look like last week?", "Show me the full thread with Bob about Q4."

For power users, Gmail operators work directly: `from:boss@company.com is:unread has:attachment`.