npx skills add https://github.com/odyssey4me/agent-skills --skill gmail与 Gmail 交互,进行邮件管理、搜索和组织。
依赖项 : pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml
安装后,验证技能是否已正确配置:
$SKILL_DIR/scripts/gmail.py check
这将检查:
如果缺少任何内容,检查命令将提供设置说明。
Gmail 使用 OAuth 2.0 进行身份验证。完整的设置说明,请参阅:
创建 ~/.config/agent-skills/google.yaml:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
oauth_client: client_id: your-client-id.apps.googleusercontent.com client_secret: your-client-secret
运行 $SKILL_DIR/scripts/gmail.py check 以触发 OAuth 流程并验证设置。
遇到作用域或身份验证错误时,请参阅 OAuth 故障排除指南。
有关每个命令的读/写分类,请参阅 permissions.md。
验证配置和连接性。
$SKILL_DIR/scripts/gmail.py check
这将验证:
存储 OAuth 2.0 客户端凭据,用于自定义 OAuth 流程。
$SKILL_DIR/scripts/gmail.py auth setup \
--client-id YOUR_CLIENT_ID \
--client-secret YOUR_CLIENT_SECRET
凭据将保存到 ~/.config/agent-skills/gmail.yaml。
清除存储的 OAuth 令牌。下一个需要身份验证的命令将自动触发重新身份验证。
$SKILL_DIR/scripts/gmail.py auth reset
当您遇到作用域或身份验证错误时使用此命令。
显示当前的 OAuth 令牌信息,无需进行 API 调用。
$SKILL_DIR/scripts/gmail.py auth status
显示:是否存储了令牌、授予的作用域、刷新令牌是否存在、令牌过期时间以及客户端 ID。
列出匹配查询条件的邮件。
# 列出最近的邮件
$SKILL_DIR/scripts/gmail.py messages list
# 搜索未读邮件
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"
# 搜索并限制最大结果数
$SKILL_DIR/scripts/gmail.py messages list --query "from:user@example.com" --max-results 20
参数:
--query: Gmail 搜索查询(可选)--max-results: 最大结果数(默认值:10)搜索查询示例:
完整的 Gmail 搜索语法,请参阅 gmail-queries.md。
常见查询:
is:unread - 未读邮件from:user@example.com - 来自发件人的邮件subject:meeting - 主题包含关键词的邮件has:attachment - 带有附件的邮件after:2024/01/01 - 指定日期之后的邮件label:important - 带有标签的邮件通过 ID 获取邮件。
# 获取完整邮件
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID
# 获取精简格式
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal
参数:
message_id: 邮件 ID(必需)--format: 邮件格式 (full, minimal, raw, metadata) - 默认值:full发送电子邮件。
# 发送简单邮件
$SKILL_DIR/scripts/gmail.py send \
--to recipient@example.com \
--subject "Hello" \
--body "This is the message body"
# 发送带抄送和密送的邮件
$SKILL_DIR/scripts/gmail.py send \
--to recipient@example.com \
--subject "Team Update" \
--body "Here's the update..." \
--cc team@example.com \
--bcc boss@example.com
参数:
--to: 收件人电子邮件地址(必需)--subject: 邮件主题(必需)--body: 邮件正文文本(必需)--cc: 抄送收件人(逗号分隔)--bcc: 密送收件人(逗号分隔)列出草稿邮件。
# 列出草稿
$SKILL_DIR/scripts/gmail.py drafts list
# 列出并自定义最大结果数
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20
参数:
--max-results: 最大结果数(默认值:10)创建草稿邮件。
# 创建草稿
$SKILL_DIR/scripts/gmail.py drafts create \
--to recipient@example.com \
--subject "Draft Subject" \
--body "This is a draft message"
# 创建带抄送的草稿
$SKILL_DIR/scripts/gmail.py drafts create \
--to recipient@example.com \
--subject "Meeting Notes" \
--body "Notes from today's meeting..." \
--cc team@example.com
参数:
--to: 收件人电子邮件地址(必需)--subject: 邮件主题(必需)--body: 邮件正文文本(必需)--cc: 抄送收件人(逗号分隔)--bcc: 密送收件人(逗号分隔)发送草稿邮件。
# 通过 ID 发送草稿
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID
参数:
draft_id: 要发送的草稿 ID(必需)列出所有 Gmail 标签。
# 列出标签
$SKILL_DIR/scripts/gmail.py labels list
创建新标签。
# 创建标签
$SKILL_DIR/scripts/gmail.py labels create "Project X"
参数:
name: 标签名称(必需)$SKILL_DIR/scripts/gmail.py check
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"
$SKILL_DIR/scripts/gmail.py messages list --query "from:boss@example.com" --max-results 5
$SKILL_DIR/scripts/gmail.py send \
--to colleague@example.com \
--subject "Quick Question" \
--body "Do you have time for a meeting tomorrow?"
# 创建草稿
$SKILL_DIR/scripts/gmail.py drafts create \
--to team@example.com \
--subject "Weekly Update" \
--body "Here's this week's update..."
# 列出草稿以获取 ID
$SKILL_DIR/scripts/gmail.py drafts list
# 发送草稿
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID
# 创建标签
$SKILL_DIR/scripts/gmail.py labels create "Project Alpha"
# 列出所有标签
$SKILL_DIR/scripts/gmail.py labels list
# 查找上周带有附件的邮件
$SKILL_DIR/scripts/gmail.py messages list --query "has:attachment newer_than:7d"
# 查找来自特定发件人的重要邮件
$SKILL_DIR/scripts/gmail.py messages list --query "from:ceo@example.com is:important"
# 查找会话中的邮件
$SKILL_DIR/scripts/gmail.py messages list --query "subject:project-alpha"
常用搜索运算符:
| 运算符 | 描述 | 示例 |
|---|---|---|
from: | 发件人电子邮件 | from:user@example.com |
to: | 收件人电子邮件 | to:user@example.com |
subject: | 主题包含 | subject:meeting |
label: | 具有标签 | label:important |
has:attachment | 具有附件 | has:attachment |
is:unread | 未读邮件 | is:unread |
is:starred | 星标邮件 | is:starred |
after: | 在日期之后 | after:2024/01/01 |
before: | 在日期之前 | before:2024/12/31 |
newer_than: | 新于时间段 | newer_than:7d |
older_than: | 旧于时间段 | older_than:30d |
使用空格(隐式 AND)或 OR 组合运算符:
# AND (隐式)
from:user@example.com subject:meeting
# OR
from:user@example.com OR from:other@example.com
# 使用括号分组
(from:user@example.com OR from:other@example.com) subject:meeting
完整参考,请参阅 gmail-queries.md。
身份验证和作用域错误不可重试。 如果命令因身份验证错误、作用域不足错误或权限被拒绝错误(退出代码 1)而失败,请停止并通知用户。不要重试或尝试自主修复问题——这些错误需要用户交互(基于浏览器的 OAuth 同意)。请引导用户查看 OAuth 故障排除指南。
可重试的错误:速率限制(HTTP 429)和临时服务器错误(HTTP 5xx)可能在短暂等待后重试成功。所有其他错误都应报告给用户。
此技能需要进行 API 调用,需要结构化输入/输出。建议使用标准能力模型。
每周安装数
133
代码仓库
GitHub 星标数
1
首次出现
Jan 24, 2026
安全审计
安装于
opencode120
gemini-cli116
codex114
cursor113
github-copilot106
amp98
Interact with Gmail for email management, search, and organization.
Dependencies : pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml
After installation, verify the skill is properly configured:
$SKILL_DIR/scripts/gmail.py check
This will check:
If anything is missing, the check command will provide setup instructions.
Gmail uses OAuth 2.0 for authentication. For complete setup instructions, see:
Create ~/.config/agent-skills/google.yaml:
oauth_client: client_id: your-client-id.apps.googleusercontent.com client_secret: your-client-secret
Run $SKILL_DIR/scripts/gmail.py check to trigger OAuth flow and verify setup.
On scope or authentication errors, see the OAuth troubleshooting guide.
See permissions.md for read/write classification of each command.
Verify configuration and connectivity.
$SKILL_DIR/scripts/gmail.py check
This validates:
Store OAuth 2.0 client credentials for custom OAuth flow.
$SKILL_DIR/scripts/gmail.py auth setup \
--client-id YOUR_CLIENT_ID \
--client-secret YOUR_CLIENT_SECRET
Credentials are saved to ~/.config/agent-skills/gmail.yaml.
Clear stored OAuth token. The next command that needs authentication will trigger re-authentication automatically.
$SKILL_DIR/scripts/gmail.py auth reset
Use this when you encounter scope or authentication errors.
Show current OAuth token information without making API calls.
$SKILL_DIR/scripts/gmail.py auth status
Displays: whether a token is stored, granted scopes, refresh token presence, token expiry, and client ID.
List messages matching a query.
# List recent messages
$SKILL_DIR/scripts/gmail.py messages list
# Search for unread messages
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"
# Search with max results
$SKILL_DIR/scripts/gmail.py messages list --query "from:user@example.com" --max-results 20
Arguments:
--query: Gmail search query (optional)--max-results: Maximum number of results (default: 10)Search Query Examples:
For complete Gmail search syntax, see gmail-queries.md.
Common queries:
is:unread - Unread messagesfrom:user@example.com - Messages from sendersubject:meeting - Messages with subject keywordhas:attachment - Messages with attachmentsafter:2024/01/01 - Messages after datelabel:important - Messages with labelGet a message by ID.
# Get full message
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID
# Get minimal format
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal
Arguments:
message_id: The message ID (required)--format: Message format (full, minimal, raw, metadata) - default: fullSend an email message.
# Send simple email
$SKILL_DIR/scripts/gmail.py send \
--to recipient@example.com \
--subject "Hello" \
--body "This is the message body"
# Send with CC and BCC
$SKILL_DIR/scripts/gmail.py send \
--to recipient@example.com \
--subject "Team Update" \
--body "Here's the update..." \
--cc team@example.com \
--bcc boss@example.com
Arguments:
--to: Recipient email address (required)--subject: Email subject (required)--body: Email body text (required)--cc: CC recipients (comma-separated)--bcc: BCC recipients (comma-separated)List draft messages.
# List drafts
$SKILL_DIR/scripts/gmail.py drafts list
# List with custom max results
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20
Arguments:
--max-results: Maximum number of results (default: 10)Create a draft email.
# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
--to recipient@example.com \
--subject "Draft Subject" \
--body "This is a draft message"
# Create draft with CC
$SKILL_DIR/scripts/gmail.py drafts create \
--to recipient@example.com \
--subject "Meeting Notes" \
--body "Notes from today's meeting..." \
--cc team@example.com
Arguments:
--to: Recipient email address (required)--subject: Email subject (required)--body: Email body text (required)--cc: CC recipients (comma-separated)--bcc: BCC recipients (comma-separated)Send a draft message.
# Send draft by ID
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID
Arguments:
draft_id: The draft ID to send (required)List all Gmail labels.
# List labels
$SKILL_DIR/scripts/gmail.py labels list
Create a new label.
# Create label
$SKILL_DIR/scripts/gmail.py labels create "Project X"
Arguments:
name: Label name (required)$SKILL_DIR/scripts/gmail.py check
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"
$SKILL_DIR/scripts/gmail.py messages list --query "from:boss@example.com" --max-results 5
$SKILL_DIR/scripts/gmail.py send \
--to colleague@example.com \
--subject "Quick Question" \
--body "Do you have time for a meeting tomorrow?"
# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
--to team@example.com \
--subject "Weekly Update" \
--body "Here's this week's update..."
# List drafts to get the ID
$SKILL_DIR/scripts/gmail.py drafts list
# Send the draft
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID
# Create a label
$SKILL_DIR/scripts/gmail.py labels create "Project Alpha"
# List all labels
$SKILL_DIR/scripts/gmail.py labels list
# Find emails with attachments from last week
$SKILL_DIR/scripts/gmail.py messages list --query "has:attachment newer_than:7d"
# Find important emails from specific sender
$SKILL_DIR/scripts/gmail.py messages list --query "from:ceo@example.com is:important"
# Find emails in a conversation
$SKILL_DIR/scripts/gmail.py messages list --query "subject:project-alpha"
Common search operators:
| Operator | Description | Example |
|---|---|---|
from: | Sender email | from:user@example.com |
to: | Recipient email | to:user@example.com |
subject: | Subject contains | subject:meeting |
label: |
Combine operators with spaces (implicit AND) or OR:
# AND (implicit)
from:user@example.com subject:meeting
# OR
from:user@example.com OR from:other@example.com
# Grouping with parentheses
(from:user@example.com OR from:other@example.com) subject:meeting
For the complete reference, see gmail-queries.md.
Authentication and scope errors are not retryable. If a command fails with an authentication error, insufficient scope error, or permission denied error (exit code 1), stop and inform the user. Do not retry or attempt to fix the issue autonomously — these errors require user interaction (browser-based OAuth consent). Point the user to the OAuth troubleshooting guide.
Retryable errors : Rate limiting (HTTP 429) and temporary server errors (HTTP 5xx) may succeed on retry after a brief wait. All other errors should be reported to the user.
This skill makes API calls requiring structured input/output. A standard-capability model is recommended.
Weekly Installs
133
Repository
GitHub Stars
1
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykFail
Installed on
opencode120
gemini-cli116
codex114
cursor113
github-copilot106
amp98
Azure RBAC 权限管理工具:查找最小角色、创建自定义角色与自动化分配
129,699 周安装
| Has label |
label:important |
has:attachment | Has attachment | has:attachment |
is:unread | Unread messages | is:unread |
is:starred | Starred messages | is:starred |
after: | After date | after:2024/01/01 |
before: | Before date | before:2024/12/31 |
newer_than: | Newer than period | newer_than:7d |
older_than: | Older than period | older_than:30d |