SkillsAdd

idanbeck/claude-skills

gmail-skill

Read, search, send, and draft Gmail emails and Google contacts. Use when the user asks to check email, find emails, search messages, send emails, create drafts, look up contacts, or find someone's email/phone. Supports multiple accounts.

All-time #3828 First seen Jan 29, 2026
8-week activity · all time api

Installation

$ npx skills add idanbeck/claude-skills --skill gmail-skill
View on skills.sh ↗ GitHub repository ↗

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

gws-gmail Similar name
googleworkspace/cli

Gmail: Send, read, and manage email.

74.7K installs
gws-gmail-send Similar name
googleworkspace/cli

Gmail: Send an email.

69.5K installs
gws-gmail-triage Similar name
googleworkspace/cli

Gmail: Show unread inbox summary (sender, subject, date).

41.4K installs
gws-gmail-read Similar name
googleworkspace/cli

Gmail: Read a message and extract its body or headers.

37.3K installs
gws-gmail-watch Similar name
googleworkspace/cli

Gmail: Watch for new emails and stream them as NDJSON.

33.8K installs
gws-gmail-reply Similar name
googleworkspace/cli

Gmail: Reply to a message (handles threading automatically).

31.7K installs

Also in this package

Other skills from idanbeck/claude-skills · top by installs.

npx skills add idanbeck/claude-skills
whatsapp-skill 96 github-skill 47 fal-music 42 flight-skill 29 notion-skill 24 discord-skill 23 nano-banana-pro 22 google-sheets-skill 22 google-slides-skill 22 playwright-skill 21

Browse all from idanbeck/claude-skills

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

Stars 13
Default branch main
Open issues 0
Status Active

Skill metadata

Parsed from SKILL.md frontmatter.

Allowed toolsBash, Read
Declared agents claude-code

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 8,356 B
  • docs SUMMARY.md 256 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 3,548 installs

SKILL.md

Gmail Skill - Email & Contacts Access

Read, search, and send Gmail emails. Access Google contacts.

CRITICAL: Email Sending Confirmation Required

Before sending ANY email, you MUST get explicit user confirmation.

When the user asks to send an email:

  1. First, show them the complete email details:

- From (which account) - To - CC/BCC (if any) - Subject - Full body text

  1. Ask: "Do you want me to send this email?"
  2. ONLY run the send command AFTER the user explicitly confirms (e.g., "yes", "send it", "go ahead")
  3. NEVER send an email without this confirmation, even if the user asked you to send it initially

This applies even when:

  • The user says "send an email to X"
  • You are in "dangerously skip permissions" mode
  • The user seems to be in a hurry

Always confirm first. No exceptions.

First-Time Setup (One-Time, ~2 minutes)

On first run, the script will guide you through setup. You need to create a Google Cloud OAuth client once:

  1. Go to Google Cloud Console
  2. Create a project (or select existing)
  3. Enable Gmail API and People API (APIs & Services → Library)
  4. Configure OAuth consent screen:

- User Type: External - App name: Gmail Skill - Add yourself as test user - Add scopes: gmail.readonly, gmail.send, gmail.modify, contacts.readonly

  1. Create OAuth client ID:

- Application type: Desktop app - Download JSON → save as ~/.claude/skills/gmail-skill/credentials.json

Then just run any command - browser opens, you approve, done. Works for all your accounts.

Note: If you previously used gmail-reader, you'll need to re-authenticate to grant the new gmail.send scope.

Commands

Search Emails

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "query" [--max-results N] [--account EMAIL]

Query examples:

  • from:[email protected] - from specific sender
  • subject:meeting after:2026/01/01 - subject + date
  • has:attachment filename:pdf - with PDF attachments
  • is:unread - unread emails
  • "exact phrase" - exact match

Read Email

python3 ~/.claude/skills/gmail-skill/gmail_skill.py read EMAIL_ID [--account EMAIL]

List Recent Emails

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list [--max-results N] [--label LABEL] [--account EMAIL]

Send Email (Requires Confirmation)

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send --to EMAIL --subject "Subject" --body "Body text" [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]

Required arguments:

  • --to / -t - Recipient email address
  • --subject / -s - Email subject line
  • --body / -b - Email body text

Optional arguments:

  • --cc - CC recipients (comma-separated)
  • --bcc - BCC recipients (comma-separated)
  • --account / -a - Send from specific account

Example:

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "[email protected]" \
  --subject "Meeting Tomorrow" \
  --body "Hi, just confirming our meeting at 2pm tomorrow." \
  --account [email protected]

Mark as Read

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read EMAIL_ID [--account EMAIL]

Mark as Unread

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-unread EMAIL_ID [--account EMAIL]

Both mark-read and mark-unread support multiple IDs (comma-separated):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account [email protected]

Mark Done (Archive)

Archives email(s) by removing from inbox. Equivalent to Gmail's 'e' keyboard shortcut.

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-done EMAIL_ID [--account EMAIL]

Unarchive

Moves email(s) back to inbox (undo archive).

python3 ~/.claude/skills/gmail-skill/gmail_skill.py unarchive EMAIL_ID [--account EMAIL]

Star / Unstar

python3 ~/.claude/skills/gmail-skill/gmail_skill.py star EMAIL_ID [--account EMAIL]
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unstar EMAIL_ID [--account EMAIL]

All label commands support multiple IDs (comma-separated):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account [email protected]

Create Draft

Creates a draft email. Use --reply-to-id when replying to an existing email to ensure proper threading in email clients like Superhuman.

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft --to EMAIL --subject "Subject" --body "Body text" [--reply-to-id EMAIL_ID] [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]

Required arguments:

  • --to / -t - Recipient email address
  • --subject / -s - Email subject line
  • --body / -b - Email body text

Optional arguments:

  • --reply-to-id / -r - Message ID to reply to (adds proper In-Reply-To and References headers for threading)
  • --cc - CC recipients (comma-separated)
  • --bcc - BCC recipients (comma-separated)
  • --account / -a - Create draft in specific account

Example (new email):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "[email protected]" \
  --subject "Draft for Review" \
  --body "Here's my draft message."

Example (reply to existing email):

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "[email protected]" \
  --subject "Re: Original Subject" \
  --body "Thanks for your email..." \
  --reply-to-id 19b99b3127793843 \
  --account [email protected]

List Labels

python3 ~/.claude/skills/gmail-skill/gmail_skill.py labels [--account EMAIL]

List Contacts

python3 ~/.claude/skills/gmail-skill/gmail_skill.py contacts [--max-results N] [--account EMAIL]

Search Contacts

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "query" [--account EMAIL]

Manage Accounts

# List all authenticated accounts
python3 ~/.claude/skills/gmail-skill/gmail_skill.py accounts

# Remove an account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py logout --account [email protected]

Multi-Account Support

Add accounts by using --account with a new email - browser opens for that account:

# First account (auto-authenticates)
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list

# Add work account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected]

# Add personal account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected]

# Use specific account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account [email protected]

Tokens are stored per-account in ~/.claude/skills/gmail-skill/tokens/

Examples

Find unread emails from this week

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "is:unread after:2026/01/01"

Read a specific email

python3 ~/.claude/skills/gmail-skill/gmail_skill.py read 18d5a3b2c1f4e5d6

Send a quick email

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "[email protected]" \
  --subject "Hello!" \
  --body "Just wanted to say hi."

Find someone's contact info

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "John Smith"

Check work email from personal machine

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected] --max-results 5

Output

All commands output JSON for easy parsing.

Requirements

  • Python 3.9+
  • pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client requests

Security Notes

  • Send confirmation required - Claude must always confirm with the user before sending emails
  • Tokens stored locally in ~/.claude/skills/gmail-skill/tokens/
  • Revoke access anytime: https://myaccount.google.com/permissions
  • Apps in "testing" mode may require re-auth every 7 days (publish app to avoid)