From gmail-organizer
This skill should be used when the user asks to "organize my gmail", "clean up my inbox", "analyze my email patterns", "create gmail filters", "label my emails", "delete old emails", "manage gmail labels", "find email patterns", "unsubscribe from newsletters", "archive old messages", "triage my inbox", "reduce inbox size", or wants to work with their Gmail inbox using gogcli (gog). Also triggers on "gmail" or "email" related organization requests.
How this skill is triggered — by the user, by Claude, or both
Slash command
/gmail-organizer:gmail-organizerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Base directory for this skill: {see the "Base directory" header above}
Base directory for this skill: {see the "Base directory" header above}
IMPORTANT: All script paths in this skill are relative to the base directory provided in the skill invocation header. When running scripts, use the full path constructed from that base directory. For example, if the base directory is /path/to/skills/gmail-organizer, run scripts as bash /path/to/skills/gmail-organizer/scripts/gmail-analyze.sh.
Organize, analyze, and clean up Gmail inboxes using the gog CLI tool (gogcli). Designed for large inboxes (10k+ messages) with a safety-first approach that requires explicit user permission for any destructive action.
gog) — installed and authenticated. Install from github.com/slstracker/gogcli. Verify with: gog gmail labels listjq installed for JSON processingGOG_ACCOUNT environment variable set, or pass --account to scriptsThese rules are non-negotiable. They are enforced at the script level AND must be followed in the workflow:
gmail-safe-batch.sh in preview mode first (no --execute flag)--execute AFTER the user has seen the preview and explicitly confirmed--force flag with gog commands to skip confirmationsRun the analysis script to understand inbox composition:
bash <base-dir>/scripts/gmail-analyze.sh
This produces a report with:
Present the analysis as a clear, organized summary. Identify the biggest opportunities for cleanup and organization.
Based on the analysis, propose:
Label taxonomy — hierarchical labels matching the user's email patterns. Common structures:
Auto/<service> for automated notificationsNews/<type> for newsletters and marketingFinance/<type> for receipts and invoicesSocial/<platform> for social media notificationsFilter rules — for high-volume recurring senders to auto-label future mail
Cleanup targets — categories safe to bulk-archive or delete (e.g., old promotions, expired notifications)
Wait for user approval before proceeding. Adjust the plan based on feedback.
Create the approved label structure:
gog gmail labels create "Parent/Child"
For each recurring pattern, create a Gmail filter:
gog gmail filters create --from '[email protected]' --add-label 'Auto/Service'
List existing filters first to avoid duplicates:
gog gmail filters list --json
Use the safe batch script for ALL batch operations. Always preview first:
# Step 1: Preview (ALWAYS do this first)
bash <base-dir>/scripts/gmail-safe-batch.sh label "from:[email protected]" "Auto/GitHub"
# Step 2: Show preview to user, ask for confirmation
# Step 3: Execute ONLY after user confirms
bash <base-dir>/scripts/gmail-safe-batch.sh label "from:[email protected]" "Auto/GitHub" --execute
For destructive operations, strictly follow this protocol:
bash <base-dir>/scripts/gmail-safe-batch.sh delete "<query>"--executeSame protocol for mark-read and archive actions.
Full inbox analysis. All operations are read-only.
Usage: bash <base-dir>/scripts/gmail-analyze.sh [--account email] [--max-sample N] [--section SECTION]
Sections: labels, categories, age, senders, domains, newsletters, unread, large, all (default)
Safety-wrapped batch operations. Preview-by-default, requires --execute for actual changes.
Usage: bash <base-dir>/scripts/gmail-safe-batch.sh <action> <gmail-query> [label] [--execute] [--max N] [--account email]
Actions:
label — Add a label to matching messages (requires label arg)
unlabel — Remove a label from matching messages (requires label arg)
archive — Remove INBOX label (requires user permission)
mark-read — Remove UNREAD label (requires user permission)
delete — Delete messages (requires user permission)
Without --execute: shows 5 sample messages and total count estimate.
With --execute: performs the operation in batches of 100.
# Search messages
gog gmail messages search '<query>' --max N --json
# Get thread detail
gog gmail thread get <threadId> --json
# Label management
gog gmail labels list --json
gog gmail labels get <label> --json
gog gmail labels create "Name"
# Filter management
gog gmail filters list --json
gog gmail filters create --from '<email>' --add-label '<label>'
# Batch operations
gog gmail batch modify <id>... --add <label> --remove <label>
gog gmail batch delete <id>...
Common operators for targeting messages:
from:[email protected] — by senderto:[email protected] — by recipientsubject:keyword — in subjectnewer_than:7d / older_than:1y — by ageis:unread / is:read — by read statushas:attachment / larger:5m — by size/attachmentcategory:promotions — Gmail categorieslabel:INBOX — by label{from:[email protected] from:[email protected]} — OR groupingreferences/gogcli-gmail-reference.md — Complete gog gmail command reference with all subcommands, flags, and output formatsreferences/organization-patterns.md — Email organization strategies, label taxonomies, filter patterns, and cleanup playbooks for different inbox typesnpx claudepluginhub bardin08/claude-kit --plugin gmail-organizerScans 3 months of Gmail inbox history to build gmail-rules.md with sender patterns, importance signals, and cleanup rules. Run once when setting up Gmail automation or when refreshing email rules.
Manages Gmail across multiple accounts: read, search, send, reply to emails, and handle labels using Python scripts and API with structured sending workflow.
Reads and searches Gmail for the configured user via the gog CLI, with structured output and Gmail query syntax support.