| name | gmail-assistant |
| description | Use when composing, sending, searching, or managing Warren's emails via gmail CLI. Covers drafting with styles, finding similar emails for context, managing groups, discovering contacts online, and email workflows. Always test to fuchengwarrenzhu@gmail.com before real sends. |
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:
- Search past emails to recipient(s) → extract patterns (greeting, tone, sign-off)
- Check available email styles → match context
- Test to fuchengwarrenzhu@gmail.com FIRST
- 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
gmail search "to:person@example.com" --max 10
gmail search "from:person@example.com" --max 10
gmail search "subject:keyword after:2024/10/01"
gmail search "has:attachment filename:pdf"
gmail list --folder INBOX --max 10
gmail folders
Read & View
gmail read <message_id>
gmail read <message_id> --full
gmail read <message_id> --full-thread
gmail thread <message_id>
gmail thread <message_id> --strip-quotes
Send & Reply
gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)"
gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)" --attachment file.pdf
gmail send --to user@example.com --subject "X" --body "Y"
gmail reply <message_id> --body "Reply text"
gmail reply <message_id> --body "Reply" --reply-all
Email Styles
gmail styles list
gmail styles show professional-formal
gmail styles validate style-name
Common styles: professional-formal, professional-friendly, casual-friend, brief-reply
Email Groups
gmail groups list
gmail groups show team
gmail groups add team person@example.com
gmail send --to @team --subject "X" --body "Y"
Workflows
gmail workflows list
gmail workflows run clear
gmail workflows start clear
gmail workflows continue <token> archive
Important Workflow Guidelines
Composing Emails
- Search past emails to recipient → extract greeting/tone/sign-off patterns
- Check relevant email styles (
gmail styles list)
- Draft combining past patterns + style + current context
- Write draft to
/tmp/email/{descriptive_name}.txt
- Open file for user review/editing (use
open command on macOS)
- Test to fuchengwarrenzhu@gmail.com first using file:
gmail send --to fuchengwarrenzhu@gmail.com --subject "..." --body "$(cat /tmp/email/{name}.txt)" --yolo
- After user confirms, send to real recipient using same file
Extracting Email Style from Past Emails
- Search relevant past emails:
gmail search "to:@harvard.edu" --folder SENT --max 10
- Read full content:
gmail read <message_id> --full
- 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
- Match these patterns in new draft for consistency
Replying to Emails
- Read original email (
gmail read <id> --full)
- Check thread if needed (
gmail thread <id>)
- Search past emails from sender to match their style
- Draft appropriate reply → review preview → send
Finding Contacts
- Search inbox:
gmail search "from:[name]"
- Search sent:
gmail search "to:[name]"
- Check groups:
gmail groups list
- If not found → search web (LinkedIn, org directories)
- Confirm with user before using new emails
Extracting Email Context
Getting Full Thread Conversation
Recommended approach:
gmail thread <message_id>
gmail thread <message_id> --strip-quotes
gmail thread <message_id> --output-format json
Alternative (manual assembly):
gmail list --folder ALL --query "keyword"
gmail read <id> --full
Finding CC'd Recipients
If gmail read output doesn't show CC/BCC recipients (current limitation), use Python workaround:
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']
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:
- Search for thread:
gmail list --folder ALL --query "subject:keywords"
- Note message IDs and thread_id from results
- Read each message for context:
gmail read <id> (or --full for body)
- Extract who's involved:
- If CC not visible, use Python workaround above
- Note all participants from From/To/CC fields
- Draft reply matching tone and context
- Include appropriate recipients (reply vs reply-all)
- Send with
--yolo to skip confirmation
Example:
gmail list --folder ALL --query "MLD courses" --output-format json
gmail read 19a5a90f97be8df8
gmail send --to "mksmith@hks.harvard.edu" --cc "Greg_Dorchak@hks.harvard.edu" --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:person@example.com OR from:person@example.com
- 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 fuchengwarrenzhu@gmail.com before real sends
- Leverage email groups for recurring distributions
- Match recipient's formality level
Common Mistakes to Avoid:
- Sending without searching first
- Wrong formality level (too casual or too formal)
- Skipping test emails
- Not using groups for recurring sends
- Getting full email when summary sufficient
References
For detailed information when needed:
references/email-styles.md - Complete styles guide
references/gmail-search-syntax.md - Full search syntax
references/api-reference.md - Complete API docs