gmail-assistant

What this skill does

# Gmail Assistant

Use this skill when working with email through the `gmail` CLI tool.

## Quick Commands

- `/gmail` - Quick reference for common gmail CLI commands
- `/gmail::setup` - Set up Gmail CLI authentication

## Core Principles

**ALWAYS before composing:**
1. Search past emails to recipient(s) → extract patterns (greeting, tone, sign-off)
2. Check available email styles → match context
3. Test to [email protected] FIRST
4. Review preview → then send to real recipient

**Progressive disclosure:**
- Start with summaries (`gmail list`, `gmail search`)
- Read full content only when needed (`--full`)
- Get thread context only if required (`gmail thread`)

---

## Essential Commands

### Search & Discovery
```bash
gmail search "to:[email protected]" --max 10        # Emails to someone
gmail search "from:[email protected]" --max 10      # Emails from someone
gmail search "subject:keyword after:2024/10/01"      # By subject + date
gmail search "has:attachment filename:pdf"           # With attachments
gmail list --folder INBOX --max 10                   # List inbox
gmail folders                                        # List all folders/labels
```

### Read & View
```bash
gmail read <message_id>                              # Summary view
gmail read <message_id> --full                       # Full content
gmail read <message_id> --full-thread                # Full content with thread context
gmail thread <message_id>                            # View entire thread
gmail thread <message_id> --strip-quotes             # View thread without quoted content
```

### Send & Reply
```bash
# Send from file (preferred for composed emails)
gmail send --to [email protected] --subject "X" --body "$(cat /tmp/email/draft.txt)"
gmail send --to [email protected] --subject "X" --body "$(cat /tmp/email/draft.txt)" --attachment file.pdf

# Send inline (for quick replies only)
gmail send --to [email protected] --subject "X" --body "Y"
gmail reply <message_id> --body "Reply text"
gmail reply <message_id> --body "Reply" --reply-all
```

### Email Styles
```bash
gmail styles list                                    # List all styles
gmail styles show professional-formal                # View specific style
gmail styles validate style-name                     # Validate format
```

**Common styles:** `professional-formal`, `professional-friendly`, `casual-friend`, `brief-reply`

### Email Groups
```bash
gmail groups list                                    # List all groups
gmail groups show team                               # Show group members
gmail groups add team [email protected]             # Add member
gmail send --to @team --subject "X" --body "Y"       # Use group
```

### Workflows
```bash
gmail workflows list                                 # List workflows
gmail workflows run clear                            # Run interactively
gmail workflows start clear                          # Start programmatic (JSON)
gmail workflows continue <token> archive             # Continue with action
```

---

## Important Workflow Guidelines

### Composing Emails
1. Search past emails to recipient → extract greeting/tone/sign-off patterns
2. Check relevant email styles (`gmail styles list`)
3. Draft combining past patterns + style + current context
4. **Write draft to `/tmp/email/{descriptive_name}.txt`**
5. Open file for user review/editing (use `open` command on macOS)
6. **Test to [email protected] first** using file: `gmail send --to [email protected] --subject "..." --body "$(cat /tmp/email/{name}.txt)" --yolo`
7. After user confirms, send to real recipient using same file

### Extracting Email Style from Past Emails
1. Search relevant past emails: `gmail search "to:@harvard.edu" --folder SENT --max 10`
2. Read full content: `gmail read <message_id> --full`
3. Note patterns:
   - **Greeting**: Formal (Dear Professor) vs. casual (Hi)
   - **Tone**: Professional, friendly, concise
   - **Structure**: Sections (Why/Preparation/Commitment), bullet points, paragraphs
   - **Sign-off**: Best regards, Thanks, etc.
   - **Signature**: Contact info format
4. Match these patterns in new draft for consistency

### Replying to Emails
1. Read original email (`gmail read <id> --full`)
2. Check thread if needed (`gmail thread <id>`)
3. Search past emails from sender to match their style
4. Draft appropriate reply → review preview → send

### Finding Contacts
1. Search inbox: `gmail search "from:[name]"`
2. Search sent: `gmail search "to:[name]"`
3. Check groups: `gmail groups list`
4. If not found → search web (LinkedIn, org directories)
5. Confirm with user before using new emails

---

## Extracting Email Context

### Getting Full Thread Conversation

**Recommended approach:**
```bash
# Use gmail thread to view entire conversation
gmail thread <message_id>                  # Show full thread
gmail thread <message_id> --strip-quotes   # Remove quoted content for clarity
gmail thread <message_id> --output-format json  # Get JSON format
```

**Alternative (manual assembly):**
```bash
# 1. Find thread
gmail list --folder ALL --query "keyword"

# 2. Get all message IDs in thread
# Note thread_id from results

# 3. Read each message with full body
gmail read <id> --full

# 4. Piece together conversation manually
```

### Finding CC'd Recipients

If `gmail read` output doesn't show CC/BCC recipients (current limitation), use Python workaround:

```python
from gmaillm.gmail_client import GmailClient

client = GmailClient()
msg = client.service.users().messages().get(
    userId='me',
    id='<message_id>',
    format='full'
).execute()

headers = msg['payload']['headers']

# Extract CC recipients
cc = [h['value'] for h in headers if h['name'].lower() == 'cc']
to = [h['value'] for h in headers if h['name'].lower() == 'to']
from_ = [h['value'] for h in headers if h['name'].lower() == 'from']

print(f"From: {from_}")
print(f"To: {to}")
print(f"CC: {cc}")
```

### Common Pattern: Draft Reply Based on Thread

**Complete workflow:**
1. Search for thread: `gmail list --folder ALL --query "subject:keywords"`
2. Note message IDs and thread_id from results
3. Read each message for context: `gmail read <id>` (or `--full` for body)
4. Extract who's involved:
   - If CC not visible, use Python workaround above
   - Note all participants from From/To/CC fields
5. Draft reply matching tone and context
6. Include appropriate recipients (reply vs reply-all)
7. Send with `--yolo` to skip confirmation

**Example:**
```bash
# Find thread
gmail list --folder ALL --query "MLD courses" --output-format json

# Read messages
gmail read 19a5a90f97be8df8

# Extract CC (if needed)
# Use Python script above

# Send reply with CC
gmail send --to "[email protected]" --cc "[email protected]" --subject "Reply" --body "..." --yolo
```

---

## Gmail Search Operators

**People:** `from:`, `to:`, `cc:`, `bcc:`
**Date:** `after:YYYY/MM/DD`, `before:YYYY/MM/DD`, `newer_than:7d`, `older_than:30d`
**Status:** `is:unread`, `is:starred`, `is:important`, `is:read`
**Content:** `subject:keyword`, `has:attachment`, `has:drive`, `filename:pdf`
**Size:** `larger:10M`, `smaller:5M`
**Boolean:** `OR`, `-` (NOT), `()` (grouping)

**Examples:**
- All correspondence: `to:[email protected] OR from:[email protected]`
- Recent thread: `subject:project after:2024/10/01`
- Unread important: `is:unread is:important`
- With PDF: `has:attachment filename:pdf`

---

## Key Things to Know

**Email Styles:**
- Located in `~/.gmaillm/email-styles/`
- Common: `professional-formal`, `professional-friendly`, `casual-friend`, `brief-reply`
- View with `gmail styles show <name>`
- Use for guidance on tone, greetings, closings

**Configuration:**
- All settings in `~/.gmaillm/`
- First time: `gmail setup-auth`
- Verify: `gmail verify`

**Best Practices:**
- Search past emails before composing → extract patterns
- Use progressive disclosure → summaries first, full content only when needed
- Test to fuchengwarrenzh