SkillsAdd

wayfind/skills · Archived

gmail

Gmail automation skill powered by gmail-agent (Go CLI). Handles email listing, sending, replying, deleting, AI-generated replies, rule-based classification, bulk historical classification, label management, filter management, and spam rescue. Trigger words: list emails, check mail, send email, reply, delete email, ai-reply, classify, bulk-classify, labels, filters, init, restore, spam, gmail.

Installation

$ npx skills add wayfind/skills --skill gmail
View on skills.sh ↗ GitHub repository ↗

Stronger alternatives

This repository is archived — consider an actively maintained alternative.

gws-gmail Similar · more installs
googleworkspace/cli

Gmail: Send, read, and manage email.

74.7K installs
gws-gmail-send Similar · more installs
googleworkspace/cli

Gmail: Send an email.

69.5K installs
gws-gmail-triage Similar · more installs
googleworkspace/cli

Gmail: Show unread inbox summary (sender, subject, date).

41.4K installs
gws-gmail-read Similar · more installs
googleworkspace/cli

Gmail: Read a message and extract its body or headers.

37.3K installs

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

gws-gmail-watch Similar name
googleworkspace/cli

Gmail: Watch for new emails and stream them as NDJSON.

33.8K installs
gws-gmail-reply Similar name
googleworkspace/cli

Gmail: Reply to a message (handles threading automatically).

31.7K installs
gws-gmail-forward Similar name
googleworkspace/cli

Gmail: Forward a message to new recipients.

30.4K installs
gws-gmail-reply-all Similar name
googleworkspace/cli

Gmail: Reply-all to a message (handles threading automatically).

29.6K installs
recipe-create-gmail-filter Similar name
googleworkspace/cli

Create a Gmail filter to automatically label, star, or categorize incoming messages.

28.3K installs
gmail-workflows Similar name
claude-office-skills/skills

Automate Gmail with intelligent workflows - attachment management, email organization, auto-arc…

4.3K installs
More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

License MIT
Default branch master
Open issues 0
Status Archived

Skill metadata

Parsed from SKILL.md frontmatter.

LicenseMIT
Declared agents claude-code

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 8,521 B
  • docs SUMMARY.md 408 B

History

  1. First recorded snapshot · 0 installs

SKILL.md

Gmail Agent Skill

First-Run Detection (run on every invocation)

Before executing any email operation, check if gmail-agent is installed:

GMAIL_AGENT_DIR="${GMAIL_AGENT_DIR:-$HOME/gmail-agent}"
ls "$GMAIL_AGENT_DIR/gmail-agent" 2>/dev/null

If not found: Tell the user gmail-agent is not set up yet, then run the installer:

bash ~/.claude/skills/gmail/scripts/install.sh

This handles everything: clone → binary download → Anthropic API key → GCP credentials (guided) → Gmail OAuth authorization. Do not proceed with email operations until it completes.

If found: Use $GMAILAGENTDIR/gmail-agent for all commands below.

Command Reference

# ── Daily Operations ────────────────────────────────────
gmail-agent list                              # List unread emails (default 20)
gmail-agent list -n 50                        # Specify count
gmail-agent list -q "in:spam"                 # List spam
gmail-agent list -q "in:trash"               # List trash
gmail-agent list -q "label:Finance"          # By label
gmail-agent list -q "from:github.com"        # By sender

gmail-agent send --to <addr> --subject <subj> --body <body>
gmail-agent reply <message-id> --body <body>  # Thread-aware reply

gmail-agent delete <message-id>              # Move to trash
gmail-agent delete --permanent <message-id>  # Permanently delete ⚠️

gmail-agent ai-reply                          # Preview AI-generated replies
gmail-agent ai-reply --dry-run=false          # Actually send
gmail-agent ai-reply --dry-run=false -n 3    # Process up to 3 emails

# ── Real-time Classification (unread only) ───────────────
gmail-agent classify                          # Preview (rules from rules.yaml)
gmail-agent classify --dry-run=false          # Execute: label + archive/spam
gmail-agent classify --dry-run=false -n 100  # Specify count

# ── Bulk Historical Classification ──────────────────────
gmail-agent bulk-classify                     # Preview (searches full mailbox)
gmail-agent bulk-classify --dry-run=false     # Execute
gmail-agent bulk-classify --only Finance/Payment --only Finance/Bank  # Selective

# ── Spam Rescue ─────────────────────────────────────────
gmail-agent restore <message-id> [id...]      # Restore from spam/trash to inbox
gmail-agent restore -q "in:spam has:userlabels"  # Bulk restore by query

# ── Label Management ────────────────────────────────────
gmail-agent labels list                       # List user labels
gmail-agent labels create "Finance/Bank"     # Create a label
gmail-agent labels delete "OldLabel"         # Delete label ⚠️ confirm required
gmail-agent labels merge "OldName" "New/Name"  # Migrate emails + delete old label ⚠️
gmail-agent labels apply labels-plan.yaml    # Execute a plan file

# ── Filter Management ───────────────────────────────────
gmail-agent filters list                      # List all filters
gmail-agent filters delete <id> [id...]       # Delete by ID ⚠️ confirm required
gmail-agent filters apply filters-plan.yaml              # Preview plan
gmail-agent filters apply filters-plan.yaml --dry-run=false  # Execute ⚠️

# ── Setup ────────────────────────────────────────────────
gmail-agent setup-gcp                         # Guided GCP credential setup
gmail-agent init                              # OAuth auth + scan + AI-generate config

Classification Architecture

Confidence Tiers (classify — real-time, unread only)

sender domain match  →  HIGH confidence  →  execute action directly
                                             output tag: [category|sender]

subject keyword match  →  LOW confidence  →  send to AI for confirmation
  AI confirms  →  execute (spam downgraded to archive)   [category|subject+ai]
  AI rejects   →  fall back to full AI classification    [category|ai]
  no AI        →  spam auto-downgraded to archive        [category|subject]

no match at all  →  AI fallback classification            [category|ai]

Core rule: spam action can only be triggered by high-confidence sender match. Subject-only match caps at archive.

AI Intervention Points

When Trigger What AI does
During classify subject-only match Confirm classification (YES/NO)
During classify no rule match Full classification fallback
After classify each batch Quality review, flag suspicious items

bulk-classify Protections

  • -has:userlabels: skips already-labeled emails, prevents cross-rule overwrites
  • spam rules: sender-only queries — subject keywords excluded from spam matching
  • Recommended execution order: Finance/Security (high confidence) → Project/DevOps → Ads

Configuration Files

rules.yaml

# Order = priority. action: keep+important / keep / archive / spam
# sender match → high confidence, direct action
# subject match → low confidence, AI confirms; spam auto-downgraded to archive
categories:
  - name: Security/Alert
    action: keep+important
    sender:              # Strong signal: domain match, high confidence
      - accounts.google.com
      - [email protected]
    subject:             # Weak signal: low confidence, needs AI confirmation
      - security alert
      - unusual activity

  - name: Finance/Payment
    action: keep
    sender:
      - apple.com
      - stripe.com
    subject:
      - invoice
      - receipt

  - name: Ads
    action: spam         # spam rules: bulk-classify uses sender-only query
    sender:              # Must have sender for spam to trigger
      - pinterest
      - mailchimp
    subject:             # In real-time classify: subject-only spam → downgraded to archive
      - unsubscribe

Design principles:

  • sender is the strong signal — alone sufficient to trigger any action
  • subject is the weak signal — alone caps at archive (spam requires AI confirmation)
  • For spam rules, keep sender list as complete as possible

See references/rules.example.yaml for a full template.

labels-plan.yaml

create:
  - Finance/Bank
  - Security/Alert
delete:
  - OldLabel
merge:
  - from: OldName
    to: Finance/Bank

filters-plan.yaml

delete:
  - <filter-id>
create:
  - from: [email protected]
    label: Project/GitHub
    archive: true

⚠️ Safety Rules (mandatory)

All destructive operations MUST call AskUserQuestion for user confirmation before executing.

Operation Command Must confirm
Move to trash delete <id> ✅
Permanent delete delete --permanent <id> ✅ state non-reversible
Delete label labels delete <name> ✅
Merge labels (deletes old) labels merge / labels apply with merge ✅
Delete filters filters delete <id> / filters apply with delete ✅

Confirmation example:

About to delete the following 3 Gmail filters. Confirm?
- ANe1BmgDb4... [from:[email protected]] → TRASH
- ANe1Bmg03p... [list:[email protected]] → TRASH
Options: [Confirm] [Cancel]
  • For bulk deletes: show the full list, never just "N items"
  • Cancel = stop and notify user

Notes

  • config.json and token.json contain account credentials — never commit
  • credentials.json is the Google OAuth client ID — never commit
  • AI reply and classify require Anthropic API key (set in config.json)
  • labels merge migrates emails then deletes the source label — irreversible