gmail

Q: How do I install gmail?

Run npx skills add https://github.com/glebis/claude-skills --skill gmail in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/gmail/ (personal) or .claude/skills/gmail/ (project).

by glebisProductivity & Automation

This skill should be used when searching, fetching, or downloading emails from Gmail. Use for queries like "search Gmail for...", "find emails from John", "show unread emails", "emails about project X", or "download attachment from email".

Installs: 253
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/glebis/claude-skills --skill gmail

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads gmail automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Gmail Search Skill

Search and fetch emails via Gmail API with flexible query options and output formats.

Prerequisites

Credentials must be configured in ~/.gmail_credentials/. Run setup to check status:

python3 scripts/gmail_search.py setup

Obtaining Gmail API Credentials

1. Create Google Cloud Project

Go to console.cloud.google.com
Click project dropdown -> "New Project"
Name it (e.g., "Gmail Agent Skill") -> Create

2. Enable Gmail API

Navigate to "APIs & Services" -> "Library"
Search for "Gmail API"
Click it and press "Enable"

3. Configure OAuth Consent Screen

Go to "OAuth consent screen" (left sidebar)
Choose "External" user type
Fill in required fields:
- App name: Gmail Agent Skill
- User support email: your email
- Developer email: your email
Click "Save and Continue", skip Scopes
On "Test users" page, add your Gmail address
Complete all steps

4. Publish the Test App

Important: Without this step, you'll get "Error 403: access_denied".

Go back to "OAuth consent screen"
Under "Publishing status", click "Publish App"
Confirm the dialog

This keeps the app in test mode (not production) but allows your test users to authenticate. You'll see an "unverified app" warning during login - click "Advanced" -> "Go to Gmail Agent Skill (unsafe)" to proceed.

Note: Test tokens expire after 7 days. Production requires Google verification.

5. Create OAuth Credentials

Go to "Credentials" (left sidebar)
Click "Create Credentials" -> "OAuth client ID"
Select "Desktop app" as application type
Name it (e.g., "Gmail Agent Client")
Click "Create"

6. Get Your Credentials

Client ID will be displayed - copy it
Client Secret: Click the download icon or view details to get the secret

7. Save Credentials

Create ~/.gmail_credentials/credentials.json:

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}

8. Authenticate

python3 scripts/gmail_search.py auth

This opens a browser. Click through the "unverified app" warning ("Advanced" -> "Go to Gmail Agent Skill"), approve access, and you're ready.

Quick Start

# Check setup status
python3 scripts/gmail_search.py setup

# Authenticate (opens browser)
python3 scripts/gmail_search.py auth

# Search emails
python3 scripts/gmail_search.py search "meeting notes"

# Search with filters
python3 scripts/gmail_search.py search --from "boss@company.com" --unread

Commands

Setup

Check configuration status:

python3 scripts/gmail_search.py setup
python3 scripts/gmail_search.py setup --json

Authenticate

Authenticate with Gmail (opens browser for OAuth):

python3 scripts/gmail_search.py auth

Scope

View or change API permission scope:

# View current scope
python3 scripts/gmail_search.py scope

# Change scope (requires re-auth)
python3 scripts/gmail_search.py scope --set readonly
python3 scripts/gmail_search.py scope --set modify
python3 scripts/gmail_search.py scope --set full

Available scopes:

readonly - Read emails only (default, recommended)
modify - Read + modify labels, mark read/unread
full - Full access including delete

Search

Search emails with free-text query or filters:

# Free-text search (uses Gmail search syntax)
python3 scripts/gmail_search.py search "project deadline"
python3 scripts/gmail_search.py search "from:john@example.com subject:invoice"

# Using helper flags
python3 scripts/gmail_search.py search --from "john@example.com"
python3 scripts/gmail_search.py search --to "me@example.com"
python3 scripts/gmail_search.py search --subject "Weekly Report"
python3 scripts/gmail_search.py search --label "INBOX"
python3 scripts/gmail_search.py search --label "work"

# Date filters (YYYY/MM/DD format)
python3 scripts/gmail_search.py search --after 2024/01/01
python3 scripts/gmail_search.py search --before 2024/12/31
python3 scripts/gmail_search.py search --after 2024/01/01 --before 2024/06/30

# Status filters
python3 scripts/gmail_search.py search --unread
python3 scripts/gmail_search.py search --starred
python3 scripts/gmail_search.py search --has-attachment

# Combined filters
python3 scripts/gmail_search.py search "invoice" --from "billing@" --has-attachment --after 2024/01/01

# Limit results
python3 scripts/gmail_search.py search "meeting" --limit 50

# Include full body (default shows snippet only)
python3 scripts/gmail_search.py search "contract" --full

# Include attachment info
python3 scripts/gmail_search.py search --has-attachment --attachments

# JSON output
python3 scripts/gmail_search.py search "project" --json

Download Attachments

Download attachments from a specific message:

# Download to default location (~/Downloads/gmail_attachments/)
python3 scripts/gmail_search.py download MESSAGE_ID

# Download to custom directory
python3 scripts/gmail_search.py download MESSAGE_ID --output /path/to/folder

# JSON output
python3 scripts/gmail_search.py download MESSAGE_ID --json

Get message ID from search results (shown in output).

Labels

List all available Gmail labels:

python3 scripts/gmail_search.py labels
python3 scripts/gmail_search.py labels --json

Output Formats

Markdown (default)

# Gmail Search Results (3 messages)

## Weekly Report
**From:** boss@company.com
**To:** me@example.com
**Date:** Mon, 25 Nov 2024 10:00:00 +0000
**ID:** `18abc123def`

> Here's the weekly report summary...

---

JSON

Add --json flag for structured output:

[
  {
    "id": "18abc123def",
    "thread_id": "18abc123def",
    "from": "boss@company.com",
    "to": "me@example.com",
    "subject": "Weekly Report",
    "date": "Mon, 25 Nov 2024 10:00:00 +0000",
    "snippet": "Here's the weekly report summary...",
    "labels": ["INBOX", "UNREAD"]
  }
]

Gmail Search Syntax

The skill supports Gmail's native search syntax in free-text queries:

Operator	Example	Description
`from:`	`from:john@example.com`	From specific sender
`to:`	`to:team@company.com`	To specific recipient
`subject:`	`subject:meeting`	In subject line
`label:`	`label:work`	Has specific label
`has:attachment`	`has:attachment`	Has attachments
`filename:`	`filename:pdf`	Attachment filename
`is:unread`	`is:unread`	Unread messages
`is:starred`	`is:starred`	Starred messages
`after:`	`after:2024/01/01`	After date
`before:`	`before:2024/12/31`	Before date
`newer_than:`	`newer_than:7d`	Within last N days
`older_than:`	`older_than:1m`	Older than N months
`in:`	`in:inbox`	In specific folder
`OR`	`from:john OR from:jane`	Either condition
`-`	`-label:spam`	Exclude
`""`	`"exact phrase"`	Exact match

Example User Requests

User says	Command
"Search Gmail for meeting notes"	`search "meeting notes"`
"Find emails from John"	`search --from "john"`
"Show unread emails"	`search --unread`
"Emails about the project from last month"	`search "project" --after 2024/10/01`
"Invoices with attachments"	`search "invoice" --has-attachment`
"Read the full email about contract"	`search "contract" --full --limit 1`
"Download attachments from that email"	`download MESSAGE_ID`
"What labels do I have?"	`labels`
"Starred emails from boss"	`search --from "boss" --starred`
"Is Gmail configured?"	`setup`

Dependencies

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

Files

~/.gmail_credentials/credentials.json - OAuth client credentials
~/.gmail_credentials/token.pickle - Cached auth token
~/.gmail_credentials/scope.txt - Current scope setting

FAQ

What does the gmail skill do?

How do I install gmail?

Run npx skills add https://github.com/glebis/claude-skills --skill gmail in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/gmail/ (personal) or .claude/skills/gmail/ (project).

Which AI agents can use gmail?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is gmail safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains gmail?

It is published by glebis in glebis/claude-skills. It has 253 recorded installs.

More from glebis/claude-skills

View all →

google-image-search

glebis/claude-skills

Search and download images via Google Custom Search API with LLM-powered selection. This skill should be used when finding images for articles, presentations, research documents, or enriching Obsidian notes with relevant visuals. Supports simple queries, batch processing from JSON config, automatic config generation from terms, and full note enrichment with automatic image insertion below headings.

Media & Creative643 installs

pdf-generation

glebis/claude-skills

Professional PDF generation from markdown using Pandoc with Eisvogel template and EB Garamond fonts. Use when converting markdown to PDF, creating white papers, research documents, marketing materials, or technical documentation. Supports both English and Russian documents with professional typography and color-coded themes. Mobile-optimized layout (6x9) by default for Telegram bot context, desktop/print layout (A4) for other contexts.

Docs & Writing482 installs

health-data

glebis/claude-skills

Query Apple Health SQLite database for vitals, activity, sleep, and workouts. Supports Markdown, JSON, and FHIR R4 output formats. This skill should be used when analyzing health metrics, generating health reports, answering questions about fitness or sleep patterns, or exporting health data in standard formats.

Education & Science393 installs

firecrawl-research

glebis/claude-skills

This skill should be used when the user requests to research topics using FireCrawl, enrich notes with web sources, search and scrape information, or write scientific/academic papers. It extracts research topics from markdown files, creates research documents with scraped sources, generates BibTeX bibliographies from research results, and provides Pandoc/MyST templates for academic writing with citation management.

Productivity & Automation379 installs

deep-research

glebis/claude-skills

This skill should be used when conducting comprehensive research on any topic using the OpenAI Deep Research API. It automates prompt enhancement through interactive clarifying questions, saves research parameters, and executes deep research with web search capabilities. Use when the user asks for in-depth analysis, investigation, research summaries, or topic exploration.

Productivity & Automation324 installs

presentation-generator

glebis/claude-skills

Generate interactive HTML presentations with neobrutalism styling, ASCII art decorations, and Agency brand colors. Outputs HTML (interactive with navigation), PNG (individual slides via Playwright), and PDF. References brand-agency skill for colors and typography. Use when creating presentations, slide decks, pitch materials, or visual summaries.

Docs & Writing320 installs

Popular productivity & automation skills

View category →

agent-browser

vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.

OfficialProductivity & Automation1.3M installs

lark-doc

open.feishu.cn

飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由；/page/ 是妙搭应用，非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。

Productivity & Automation815.7K installs

lark-base

open.feishu.cn

飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。

Productivity & Automation815K installs

lark-drive

open.feishu.cn

飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签（secure labels）和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。

Productivity & Automation815K installs

lark-shared

open.feishu.cn

Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling notice JSON.

Productivity & Automation814.8K installs

lark-im

open.feishu.cn

飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。

Productivity & Automation814.1K installs

gmail

Install

Install

Describe the task

Review the result

SKILL.md

Gmail Search Skill

Prerequisites

Obtaining Gmail API Credentials

1. Create Google Cloud Project

2. Enable Gmail API

3. Configure OAuth Consent Screen

4. Publish the Test App

5. Create OAuth Credentials

6. Get Your Credentials

7. Save Credentials

8. Authenticate

Quick Start

Commands

Setup

Authenticate

Scope

Search

Download Attachments

Labels

Output Formats

Markdown (default)

JSON

Gmail Search Syntax

Example User Requests

Dependencies

Files

FAQ

More from glebis/claude-skills

Popular productivity & automation skills