AI Skills
gmail-skill

gmail-skill

讀取、搜尋、寄送和草擬 Gmail 郵件及 Google 聯絡人。當使用者要求檢查郵件、尋找郵件、搜尋訊息、寄送郵件、建立草稿、查詢聯絡人或尋找某人的電子郵件/電話時使用。支援多個帳戶。

12星標
3分支
更新於 2026/7/22
獲取技能源代碼

相關技能

flox-environments24萬cloud11萬api-security-testing5.9萬
SKILL.md
唯讀
名稱
gmail-skill
描述

讀取、搜尋、寄送和草擬 Gmail 郵件及 Google 聯絡人。當使用者要求檢查郵件、尋找郵件、搜尋訊息、寄送郵件、建立草稿、查詢聯絡人或尋找某人的電子郵件/電話時使用。支援多個帳戶。

Gmail 技能 - 電子郵件與聯絡人存取

讀取、搜尋和寄送 Gmail 郵件。存取 Google 聯絡人。

重要：寄送郵件前需確認

在寄送任何郵件之前，你必須取得使用者明確的確認。

當使用者要求寄送郵件時：

  1. 首先，向他們顯示完整的郵件詳細資訊：
    • 寄件者（哪個帳戶）
    • 收件者
    • 副本/密件副本（如果有）
    • 主旨
    • 完整內文
  2. 詢問：「你要我寄送這封郵件嗎？」
  3. 只有在使用者明確確認後（例如「是」、「寄送」、「請寄」），才能執行寄送指令
  4. 即使使用者一開始要求你寄送，也絕不能在未經確認的情況下寄送郵件

以下情況同樣適用：

  • 使用者說「寄一封郵件給 X」
  • 你處於「危險跳過權限」模式
  • 使用者似乎很急

一律先確認，沒有例外。

首次設定（一次性，約 2 分鐘）

首次執行時，腳本會引導你完成設定。你需要建立一次 Google Cloud OAuth 用戶端：

  1. 前往 Google Cloud 控制台
  2. 建立專案（或選取現有專案）
  3. 啟用 Gmail API 和 People API（API 和服務 → 程式庫）
  4. 設定 OAuth 同意畫面：
    • 使用者類型：外部
    • 應用程式名稱：Gmail Skill
    • 將自己加入測試使用者
    • 新增範圍：gmail.readonly、gmail.send、gmail.modify、contacts.readonly
  5. 建立 OAuth 用戶端 ID：
    • 應用程式類型：桌面應用程式
    • 下載 JSON → 儲存為 ~/.claude/skills/gmail-skill/credentials.json

然後執行任何指令即可 - 瀏覽器會開啟，你核准後就完成。適用於你的所有帳戶。

注意： 如果你之前使用過 gmail-reader，你需要重新驗證以授予新的 gmail.send 範圍。

指令

搜尋郵件

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

查詢範例：

  • from:john@example.com - 來自特定寄件者
  • subject:meeting after:2026/01/01 - 主旨 + 日期
  • has:attachment filename:pdf - 有 PDF 附件
  • is:unread - 未讀郵件
  • "exact phrase" - 完全符合

讀取郵件

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

列出近期郵件

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

寄送郵件（需確認）

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send --to EMAIL --subject "主旨" --body "內文" [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]

必要引數：

  • --to / -t - 收件者電子郵件地址
  • --subject / -s - 郵件主旨
  • --body / -b - 郵件內文

選用引數：

  • --cc - 副本收件者（逗號分隔）
  • --bcc - 密件副本收件者（逗號分隔）
  • --account / -a - 從特定帳戶寄送

範例：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "recipient@example.com" \
  --subject "明天會議" \
  --body "嗨，確認一下我們明天下午 2 點的會議。" \
  --account work@company.com

標記為已讀

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

標記為未讀

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

mark-read 和 mark-unread 都支援多個 ID（逗號分隔）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account user@gmail.com

標記為完成（封存）

將郵件從收件匣移除（封存）。等同於 Gmail 的 'e' 鍵盤快捷鍵。

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

取消封存

將郵件移回收件匣（取消封存）。

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

加星號 / 取消星號

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]

所有標籤指令都支援多個 ID（逗號分隔）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account user@gmail.com

建立草稿

建立草稿郵件。回覆現有郵件時使用 --reply-to-id，以確保在 Superhuman 等郵件用戶端中正確的對話串接。

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft --to EMAIL --subject "主旨" --body "內文" [--reply-to-id EMAIL_ID] [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]

必要引數：

  • --to / -t - 收件者電子郵件地址
  • --subject / -s - 郵件主旨
  • --body / -b - 郵件內文

選用引數：

  • --reply-to-id / -r - 要回覆的郵件 ID（加入正確的 In-Reply-To 和 References 標頭以利對話串接）
  • --cc - 副本收件者（逗號分隔）
  • --bcc - 密件副本收件者（逗號分隔）
  • --account / -a - 在特定帳戶建立草稿

範例（新郵件）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "recipient@example.com" \
  --subject "草稿待審" \
  --body "這是我的草稿訊息。"

範例（回覆現有郵件）：

python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "sender@example.com" \
  --subject "Re: 原始主旨" \
  --body "謝謝你的來信..." \
  --reply-to-id 19b99b3127793843 \
  --account work@company.com

列出標籤

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

列出聯絡人

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

搜尋聯絡人

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

管理帳戶

# 列出所有已驗證的帳戶
python3 ~/.claude/skills/gmail-skill/gmail_skill.py accounts

# 移除帳戶
python3 ~/.claude/skills/gmail-skill/gmail_skill.py logout --account user@gmail.com

多帳戶支援

使用 --account 搭配新的電子郵件來新增帳戶 - 瀏覽器會開啟以驗證該帳戶：

# 第一個帳戶（自動驗證）
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list

# 新增工作帳戶
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com

# 新增個人帳戶
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account personal@gmail.com

# 使用特定帳戶
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account work@company.com

Token 會依帳戶儲存在 ~/.claude/skills/gmail-skill/tokens/

範例

尋找本週的未讀郵件

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

讀取特定郵件

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

寄送快速郵件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "friend@example.com" \
  --subject "哈囉！" \
  --body "只是想打個招呼。"

尋找某人的聯絡資訊

python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "王小明"

從個人電腦檢查工作郵件

python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com --max-results 5

輸出

所有指令輸出 JSON 格式，便於解析。

需求

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

安全注意事項

  • 寄送郵件需確認 - Claude 在寄送郵件前必須先與使用者確認
  • Token 儲存在本機 ~/.claude/skills/gmail-skill/tokens/
  • 隨時撤銷存取權限：https://myaccount.google.com/permissions
  • 「測試」模式中的應用程式可能每 7 天需要重新驗證（發布應用程式可避免）