jeffvincent/gmail-skill

Gmail Manager Skill

This skill provides comprehensive Gmail integration through lightweight CLI scripts. All operations are token-efficient and composable.

First-Time Setup

Before using this skill, you must set up OAuth authentication:

1. Install dependencies:

   cd ~/.claude/skills/gmail-skill && npm install
   

2. Set up Google Cloud credentials:

   • Follow the guide in docs/google-cloud-setup.md
   • Download credentials.json and save to scripts/auth/credentials.json

3. Authenticate:

   cd ~/.claude/skills/gmail-skill && npm run setup
   

This will open a browser for Google OAuth and save your token locally.

Multi-Account Support

The Gmail skill supports multiple accounts (e.g., personal and work email):

Add Additional Accounts

# Add a second account (from skill directory)
npm run setup -- --account work

# Add a third account
npm run setup -- --account personal

Each account needs separate OAuth authentication.

Manage Accounts

# List all configured accounts
node scripts/manage-accounts.js --list

# Set default account (used when --account is not specified)
node scripts/manage-accounts.js --set-default work

# Remove an account
node scripts/manage-accounts.js --remove old-account

Using Specific Accounts

All Gmail operations support the --account parameter:

# Send email from work account
node gmail-send.js --account work --to "[email protected]" --subject "..." --body "..."

# Send from personal (or omit --account to use default)
node gmail-send.js --account personal --to "[email protected]" --subject "..." --body "..."

# Search work emails
node gmail-search.js --account work --query "is:unread"

If --account is not specified, the default account is used.

Usage Guidelines

1. Read Documentation On-Demand

When first using Gmail operations, read the comprehensive README:

cat ~/.claude/skills/gmail-skill/README.md

This provides detailed usage examples for all operations.

2. Execute Scripts via Bash

All scripts are in the scripts/ directory and output JSON for easy parsing:

cd ~/.claude/skills/gmail-skill/scripts

3. Parse JSON Output

All scripts return JSON. Parse the output and present relevant information to the user in a friendly format.

4. Chain Operations

Save intermediate results to files when chaining operations:

# Search for emails
node gmail-search.js --query "from:[email protected]" > /tmp/search-results.json

# Read first message from results
MESSAGE_ID=$(cat /tmp/search-results.json | jq -r '.messages[0].id')
node gmail-read.js --id "$MESSAGE_ID"

Available Operations

Send Email

node gmail-send.js --to "[email protected]" --subject "Subject" --body "Body text"

Email Formatting: The --body parameter accepts markdown and automatically converts it to styled HTML for email rendering. Use markdown headers (##), bold (**text**), lists (- item), and paragraphs (double newlines) for well-formatted emails. If you need raw HTML, use --html instead.

IMPORTANT: When sending long-form content (analyses, reports, briefings), ALWAYS use markdown formatting:

• Use ## headers to create visual sections
• Use **bold** for emphasis and key terms
• Use - bullet lists for structured points
• Use blank lines between paragraphs
• Use --- for horizontal rule separators between major sections

For long emails, use --body-file /path/to/file.md instead of --body. Write the markdown content to a temp file first, then pass the path. This avoids shell argument length limits.

Search Emails

node gmail-search.js --query "is:unread" --limit 10

Read Message

node gmail-read.js --id "MESSAGE_ID"

Manage Labels

# List all labels
node gmail-labels.js --action list

# Add label to message
node gmail-labels.js --action add --id "MESSAGE_ID" --label "Important"

Manage Drafts

# Create draft
node gmail-drafts.js --action create --to "[email protected]" --subject "Subject" --body "Draft body"

# Send draft
node gmail-drafts.js --action send --id "DRAFT_ID"

Error Handling

If scripts fail:

• Check that token.json exists in scripts/auth/
• If token is expired, run npm run setup again
• Verify the user granted all required Gmail API permissions

Best Practices

1. Always change to the scripts directory first to ensure relative paths work
2. Parse JSON output and present user-friendly summaries
3. Validate user input before passing to scripts
4. Handle errors gracefully and provide helpful error messages
5. Use search operators for precise email filtering (see README.md)

Token Efficiency

This skill is designed for minimal token usage:

• Documentation loaded only when needed
• Scripts are small and focused
• JSON output is compact and parseable
• No persistent server overhead