Agent skill

Gmail

Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels.

Apache-2.0Auto-check passedProductivity & Automation

Install Gmail

skills CLI

$ npx skills add sanjay3290/ai-skills --skill gmail -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install sanjay3290/ai-skills gmail --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/sanjay3290/ai-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/gmail .claude/skills/gmail && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "gmail" agent skill from https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail into .claude/skills/gmail/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gmail", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add sanjay3290/ai-skills --skill gmail -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install sanjay3290/ai-skills gmail --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/sanjay3290/ai-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/gmail .agents/skills/gmail && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "gmail" agent skill from https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail into .agents/skills/gmail/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gmail", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add sanjay3290/ai-skills --skill gmail -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install sanjay3290/ai-skills gmail --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/sanjay3290/ai-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/gmail .cursor/skills/gmail && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "gmail" agent skill from https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail into .cursor/skills/gmail/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gmail", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/sanjay3290/ai-skills.git --path skills/gmail

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add sanjay3290/ai-skills --skill gmail -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install sanjay3290/ai-skills gmail --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/sanjay3290/ai-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/gmail .gemini/skills/gmail && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "gmail" agent skill from https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail into .gemini/skills/gmail/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gmail", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install sanjay3290/ai-skills gmail

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add sanjay3290/ai-skills --skill gmail -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/sanjay3290/ai-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/gmail .github/skills/gmail && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "gmail" agent skill from https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail into .github/skills/gmail/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gmail", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add sanjay3290/ai-skills --skill gmail -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install sanjay3290/ai-skills gmail --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/sanjay3290/ai-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/gmail .opencode/skills/gmail && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "gmail" agent skill from https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail into .opencode/skills/gmail/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "gmail", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: gmail
GitHub stars: 430
Token cost: ~1.2k tokens
SKILL.md length: 205 words
Files: 6 (incl. scripts)
Skills in repo: 24
Repo updated: Sep 10, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels.

User asks to: search email
SKILL.md covers First-Time Setup, Commands, Gmail Query Syntax and Common Label IDs, plus 1 more section
Runs Python scripts from its folder; calls python
Create email draft

What it does

Gmail is an agent skill from sanjay3290/ai-skills. Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels. Use when user asks to: search email, read email, send email, create email draft, mark as read, archive email, star email, or manage Gmail labels. Lightweight alternative to full Google Workspace MCP server with standalone OAuth authentication.

Its SKILL.md is about 1.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 6 other files, including scripts (for example `README.md`, `scripts/auth.py` and `scripts/gmail.py`).

It sits in Productivity & Automation, covering Email management and Cloud office suites. It works with Gmail, Model Context Protocol and Google Workspace. The repository describes itself as: 24 cross-platform agent skills for Claude Code, Cursor, Codex & Gemini CLI — databases, messaging, research, TTS, DevOps, and Google Workspace. The licence is Apache-2.0.

When your agent uses it

User asks to: search email
Create email draft
Manage Gmail labels

Example prompts

“/gmail”

Requirements

Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit 281d88d. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 3 files in scripts/ (Python), which the agent can run.
Shell commands in SKILL.md call:
- python
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Gmail loads about 1.2k tokens when it runs. Until then it costs about 87 tokens; SKILL.md has 205 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~87
When it runs · the whole SKILL.md, loaded when a task matches: ~1.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from sanjay3290/ai-skills at commit 281d88d, republished under its Apache-2.0 licence (© sanjay3290). 205 words, ~1,237 tokens.

Download SKILL.mdSave it as .claude/skills/gmail/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.

name: gmail
description: Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels. Use when user asks to: search email, read email, send email, create email draft, mark as read, archive email, star email, or manage Gmail labels. Lightweight alternative to full Google Workspace MCP server with standalone OAuth authentication.
license: Apache-2.0
metadata.author: sanjay3290
metadata.version: 1.0

Gmail

Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.

⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.

First-Time Setup

Authenticate with Google (opens browser):

bash

python scripts/auth.py login

Check authentication status:

bash

python scripts/auth.py status

Logout when needed:

bash

python scripts/auth.py logout

Commands

All operations via scripts/gmail.py. Auto-authenticates on first use if not logged in.

Search Emails

bash

# Search with Gmail query syntax
python scripts/gmail.py search "from:someone@example.com is:unread"

# Search recent emails (no query returns all)
python scripts/gmail.py search --limit 20

# Filter by label
python scripts/gmail.py search --label INBOX --limit 10

# Include spam and trash
python scripts/gmail.py search "subject:important" --include-spam-trash

Read Email Content

bash

# Get full message content
python scripts/gmail.py get MESSAGE_ID

# Get just metadata (headers)
python scripts/gmail.py get MESSAGE_ID --format metadata

# Get minimal response (IDs only)
python scripts/gmail.py get MESSAGE_ID --format minimal

Send Emails

bash

# Send a simple email
python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message body"

# Send with CC and BCC
python scripts/gmail.py send --to "user@example.com" --cc "cc@example.com" --bcc "bcc@example.com" \
  --subject "Team Update" --body "Update message"

# Send from an alias (must be configured in Gmail settings)
python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message" \
  --from "Mile9 Accounts <accounts@mile9.io>"

# Send HTML email
python scripts/gmail.py send --to "user@example.com" --subject "HTML Email" \
  --body "<h1>Hello</h1><p>HTML content</p>" --html

Draft Management

bash

# Create a draft
python scripts/gmail.py create-draft --to "user@example.com" --subject "Draft Subject" \
  --body "Draft content"

# Send an existing draft
python scripts/gmail.py send-draft DRAFT_ID

Modify Messages (Labels)

bash

# Mark as read (remove UNREAD label)
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD

# Mark as unread
python scripts/gmail.py modify MESSAGE_ID --add-label UNREAD

# Archive (remove from INBOX)
python scripts/gmail.py modify MESSAGE_ID --remove-label INBOX

# Star a message
python scripts/gmail.py modify MESSAGE_ID --add-label STARRED

# Unstar a message
python scripts/gmail.py modify MESSAGE_ID --remove-label STARRED

# Mark as important
python scripts/gmail.py modify MESSAGE_ID --add-label IMPORTANT

# Multiple label changes at once
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD --add-label STARRED

List Labels

bash

# List all Gmail labels (system and user-created)
python scripts/gmail.py list-labels

Gmail Query Syntax

Gmail supports powerful search operators:

Query	Description
`from:user@example.com`	Emails from a specific sender
`to:user@example.com`	Emails to a specific recipient
`subject:meeting`	Emails with "meeting" in subject
`is:unread`	Unread emails
`is:starred`	Starred emails
`is:important`	Important emails
`has:attachment`	Emails with attachments
`after:2024/01/01`	Emails after a date
`before:2024/12/31`	Emails before a date
`newer_than:7d`	Emails from last 7 days
`older_than:1m`	Emails older than 1 month
`label:work`	Emails with a specific label
`in:inbox`	Emails in inbox
`in:sent`	Sent emails
`in:trash`	Trashed emails

Combine with AND (space), OR, or - (NOT):

bash

python scripts/gmail.py search "from:boss@company.com is:unread newer_than:1d"
python scripts/gmail.py search "subject:urgent OR subject:important"
python scripts/gmail.py search "from:newsletter@example.com -is:starred"

Common Label IDs

Label	ID
Inbox	`INBOX`
Sent	`SENT`
Drafts	`DRAFT`
Spam	`SPAM`
Trash	`TRASH`
Starred	`STARRED`
Important	`IMPORTANT`
Unread	`UNREAD`

Token Management

Tokens stored securely using the system keyring:

macOS: Keychain
Windows: Windows Credential Locker
Linux: Secret Service API (GNOME Keyring, KDE Wallet, etc.)

Service name: gmail-skill-oauth

Tokens automatically refresh when expired using Google's cloud function.

Files

SKILL.md and 5 other files (scripts) in skills/gmail of sanjay3290/ai-skills.

SKILL.md
README.md
requirements.txt
scripts/auth.py
scripts/gmail.py
scripts/requirements.txt

Open the folder on GitHubat commit 281d88d

Compare with similar skills

Gmail next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Gmail compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Gmail this skillsanjay3290/ai-skills	430	—	~1.2k	Automated safety check: Pass	Apache-2.0	27 days ago
Gmail Query Syntaxprovos/ironcurtain	613	—	~971	Automated safety check: Pass	Apache-2.0	today
Apple Mail Setupdavekilleen/Dex	493	—	~2.5k	Automated safety check: Pass	Custom licence	5 days ago
Bootstrap Google Toolsgoogle/adk-recipes	10k	—	~5k	Automated safety check: Warn	Apache-2.0	2 days ago
Gwskv0906/pm-kit	138	—	~1.6k	Automated safety check: Pass	MIT	3 mo ago
Google Workspaceswarmclawai/swarmclaw	687	—	~680	Automated safety check: Pass	MIT	3 mo ago

Similar skills

Gmail Query Syntax
provos/ironcurtain
Reference for Gmail's search query syntax — operators like is:sent, newerthan:, from:, has:attachment, label:, and how they compose.
613 GitHub stars~971 tokensUpdated today
Productivity & AutomationAuto-check passed
Apple Mail Setup
davekilleen/Dex
Set up and verify Apple Mail search on macOS, including the search index that silently returns nothing when it was never built.
493 GitHub stars~2.5k tokensUpdated 5 days ago
Documents & OfficeAuto-check passed
Bootstrap Google Tools
google/adk-recipes
Official
Install/auth CLIs the sandbox lacks - gws (Drive, Gmail, Sheets, Calendar), gcloud, agents-cli, mcp-cli (MCP servers).
10k GitHub stars~5k tokensUpdated 2 days ago
Agent WorkflowsAuto-check: warnings
Gws
kv0906/pm-kit
This skill should be used when the user asks to "set up gws", "install Google Workspace CLI", "connect Gmail to Claude", "manage Google Drive from terminal", "send email from CLI", "check my…
138 GitHub stars~1.6k tokensUpdated 3 mo ago
Documents & OfficeAuto-check passed
Google Workspace
swarmclawai/swarmclaw
Use Google Workspace CLI (gws) for Drive, Docs, Sheets, Gmail, Calendar, Chat, and related Workspace API tasks.
687 GitHub stars~680 tokensUpdated 3 mo ago
Documents & OfficeAuto-check passed
Google Workspace CLI
hoodini/ai-agents-skills
Interact with all Google Workspace APIs via the gws CLI. An agent skill from hoodini/ai-agents-skills.
282 GitHub stars~10k tokensUpdated 2 mo ago
Documents & OfficeAuto-check: notes

Questions about Gmail

What does Gmail do?

Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels. Gmail is an agent skill from sanjay3290/ai-skills. Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels.

When should I use Gmail?

Gmail fits situations like: user asks to: search email; create email draft; manage Gmail labels.

How do I install Gmail in Claude Code?

Run `npx skills add sanjay3290/ai-skills --skill gmail -a claude-code`. Or copy the skill folder (skills/gmail in sanjay3290/ai-skills) into .claude/skills/gmail in your project. Claude Code loads it when a task matches its description.

How do I install Gmail in Codex?

Run `npx skills add sanjay3290/ai-skills --skill gmail -a codex`. Or copy the skill folder (skills/gmail in sanjay3290/ai-skills) into .agents/skills/gmail in your project. Codex loads it when a task matches its description.

Can I use Gmail in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add sanjay3290/ai-skills --skill gmail -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/gmail, .gemini/skills/gmail, .github/skills/gmail and .opencode/skills/gmail in your project.

What does Gmail need to run?

Going by SKILL.md and its folder, Gmail needs Python for the scripts in its folder and the command-line tools its instructions call (python). Our summary lists: Python 3.

Does Gmail access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Gmail safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Gmail use?

Gmail is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Gmail use?

About 1.2k tokens (SKILL.md is roughly 4.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Gmail?

Skills that share tags, products or a category with Gmail: Gmail Query Syntax (provos/ironcurtain, 613 stars), Apple Mail Setup (davekilleen/Dex, 493 stars), Bootstrap Google Tools (google/adk-recipes, 10k stars) and Gws (kv0906/pm-kit, 138 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Gmail?

sanjay3290 (a GitHub user) maintains it in sanjay3290/ai-skills, which has 430 GitHub stars. The repository holds 24 skills in this directory. The repository was last updated on September 10, 2026.

Source: sanjay3290/ai-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Gmail

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Gmail

First-Time Setup

Commands

Search Emails

Read Email Content

Send Emails

Draft Management

Modify Messages (Labels)

List Labels

Gmail Query Syntax

Common Label IDs

Token Management

Files

Compare with similar skills

Similar skills

More from sanjay3290/ai-skills

Related

Questions about Gmail