# gmail-skill

Reads, searches and sends Gmail messages, and looks up Google contacts. Useful when the agent has to triage a mailbox or prepare a draft.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3600 installs · ★ 14
- Author: idanbeck
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/idanbeck/claude-skills/tree/HEAD/gmail-skill/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/gmail-skill

## What it does

The skill hands your agent Gmail access through `gmail_skill.py`. Search takes the usual Gmail operators: `from:`, `subject:`, `has:attachment`, `is:unread`. You also get reading by message ID, a recent-message list, labels, stars, archive and unarchive. Google contacts are covered too, with listing and lookup by name, email or phone.

First run needs a one-time OAuth client in Google Cloud Console: enable the Gmail API and People API, add yourself as a test user, download the JSON and save it as `~/.claude/skills/gmail-skill/credentials.json`. After that the browser opens on its own. Multiple accounts are supported, and `--account` picks which one to use.

Sending is deliberately cautious. The skill prints the whole message first — sender account, recipient, subject, body — and waits for an explicit yes before running the send command. That holds even if you asked it to send right away, and even with permission prompts skipped. Coming from gmail-reader? You will re-authenticate, because the `gmail.send` scope is new.

## Requirements
- Works with: Gmail

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add idanbeck/claude-skills --skill gmail-skill -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/gmail-skill/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/gmail-skill/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add idanbeck/claude-skills --skill gmail-skill -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/gmail-skill/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add idanbeck/claude-skills --skill gmail-skill -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/gmail-skill/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install idanbeck/claude-skills gmail-skill
```

2. **Manually: put the files in place**
- File: `.github/skills/gmail-skill/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add idanbeck/claude-skills --skill gmail-skill -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/idanbeck/claude-skills --path gmail-skill
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/gmail-skill/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add idanbeck/claude-skills --skill gmail-skill -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/idanbeck/claude-skills/tree/HEAD/gmail-skill/SKILL.md

## When to use it
- find messages from one sender within a date range
- draft a reply inside an existing thread
- check a work inbox without opening a browser
- look up someone's email or phone in contacts
- send a message with an attachment from the terminal

## Example prompts
- find unread emails with PDF attachments from the last week
- draft a reply to message 19b99b3127793843 from work@company.com
- list contacts whose name contains Ivan

## Similar
- [gws-gmail](https://affpapa.org/en/nevibecode/skills/gws-gmail.md) — skill · 82100 installs
- [gws-gmail-send](https://affpapa.org/en/nevibecode/skills/gws-gmail-send.md) — skill · 74800 installs
- [google](https://affpapa.org/en/nevibecode/skills/vercel-labs-google.md) — skill · 364 installs
- [gmail-workflows](https://affpapa.org/en/nevibecode/skills/gmail-workflows.md) — skill · 5000 installs
- [inbox-triage](https://affpapa.org/en/nevibecode/skills/inbox-triage.md) — skill · 408 installs
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12791

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md