Gmail Attachment Downloader

Download Gmail attachments through IMAP when the user wants to pull invoices, statements, or other files from Gmail into a local folder. Use it when the task...

Security Scan

The skill appears to do exactly what it claims—download Gmail attachments via IMAP using an app password—and its code and instructions are consistent with that purpose, though a few metadata omissions and runtime assumptions should be noted before use.

Purpose & Capability

Name/description match the included script: the Python script connects to imap.gmail.com, searches messages, and writes attachments locally. Asking for a Gmail address and an app password is appropriate for the stated purpose. The registry metadata, however, does not declare the environment variables (GMAIL_USER/GMAIL_PASS) or a required runtime (python3), which is an omission.

Instruction Scope

SKILL.md limits scope to reading mail and downloading attachments; it explicitly says it does not modify or delete mailbox contents. The runtime instructions ask for only the Gmail credentials and filters required for search; they instruct running the bundled script with explicit arguments rather than performing arbitrary system scans. No instructions ask the agent to read unrelated files or exfiltrate data to external endpoints.

Install Mechanism

There is no install spec (instruction-only + bundled scripts) so nothing will be downloaded during installation. Risk is limited to running the included Python script. The skill assumes a Python runtime is available but does not declare it.

Credentials

The script legitimately requires Gmail credentials (app password) and supports GMAIL_USER/GMAIL_PASS environment variables. Those credentials are proportional to the task. However, the skill metadata did not declare required env vars or a primary credential, which is a mismatch that reduces transparency and should be corrected.

Persistence & Privilege

The skill is not set to always:true and does not request special platform privileges. It writes attachments to the user-specified local folder (expected behavior) and does not modify other skills or agent settings.

Assessment

This skill is coherent for downloading Gmail attachments via IMAP, but review these points before installing or running: 1) It requires a Gmail account with IMAP enabled and an app password (not your normal login password). 2) The registry metadata omits the environment variables (GMAIL_USER, GMAIL_PASS) and the assumed runtime (python3); treat that as a transparency gap. 3) Inspect the bundled script yourself to confirm there are no hidden network calls or surprises (the visible code connects only to imap.gmail.com and writes files locally). 4) Run the script in a safe environment (local machine or isolated VM) and consider creating a dedicated app password for this use. 5) When providing a save folder, pick a directory you control and review the downloaded files before opening them.

Use this skill when the user wants files downloaded from Gmail to the local machine.

When To Use

Trigger this skill when the user asks to:

• Download Gmail attachments in bulk
• Export invoices, statements, or receipts from Gmail
• Filter Gmail attachments by sender, subject, date range, extension, or limit
• Save Gmail attachments into a local folder without using Google Cloud APIs

Do not use this skill for:

• Sending email
• Modifying or deleting mailbox contents
• Managing Google OAuth projects

Inputs To Collect

Collect or infer these inputs before running the script:

• gmail_user: Gmail address
• gmail_pass: Gmail app password
• sender: optional sender filter
• subject: optional subject filter
• since: optional start date in DD-Mon-YYYY
• before: optional end date in DD-Mon-YYYY
• extensions: optional comma-separated extension list such as .pdf,.ofd
• save_folder: destination folder on the local machine
• max_results: optional safety limit for matched messages
• dry_run: optional preview mode when the user wants to inspect matches first

If the user did not specify save_folder, choose a clear folder under their home directory and state it explicitly before running.

Execution

Run the bundled script with explicit arguments instead of editing source files.

python3 scripts/download_gmail_attachments.py \
  --gmail-user "$GMAIL_USER" \
  --gmail-pass "$GMAIL_PASS" \
  --sender "[e-mail]" \
  --subject "发票" \
  --since "01-Jan-2025" \
  --extensions ".pdf,.ofd" \
  --save-folder "~/Documents/walmart-invoices" \
  --max-results 200

Preview matches without writing files:

python3 scripts/download_gmail_attachments.py \
  --gmail-user "$GMAIL_USER" \
  --gmail-pass "$GMAIL_PASS" \
  --sender "[e-mail]" \
  --extensions ".pdf,.ofd" \
  --save-folder "~/Documents/walmart-invoices" \
  --dry-run

Environment variables are also supported:

• GMAIL_USER
• GMAIL_PASS

Workflow

1. Confirm the user has Gmail IMAP enabled and an app password.
2. Decide the destination folder and filters.
3. Run scripts/download_gmail_attachments.py with explicit arguments.
4. Report: downloaded count, skipped count, and destination folder. If --summary-json is used, prefer reading that file for the final report.
5. If authentication fails, tell the user to re-check IMAP and the app password.

Failure Handling

• If GMAIL_USER or GMAIL_PASS is missing, stop and ask for it.
• If mailbox auto-detection cannot find Gmail All Mail, fall back to INBOX.
• If no messages match, suggest loosening sender/subject/date filters.
• If downloads are zero, suggest removing extension filtering.

Resources

• Setup details: references/setup.md
• Script entry point: scripts/download_gmail_attachments.py