Description

Reads emails from Gmail (all folders/labels) using the gog CLI. Use when the user asks to check email, read inbox, show unread messages, list folders, search...

README (SKILL.md)

Email Reader

Name: gmailcleaner
Author: coorops25

Lee correos de Gmail usando el CLI gog. Requiere que gog auth esté configurado. Si no lo está, ejecuta el setup primero.

Setup inicial (solo una vez)

gog auth credentials /ruta/a/client_secret.json
gog auth add $GOG_ACCOUNT --services gmail
gog auth list   # verificar que quedó bien

Cuándo usar esta skill

"Revisa mi correo"
"¿Qué correos nuevos tengo?"
"Muéstrame los no leídos de hoy"
"Lee los correos de Juan"
"Busca correos sobre la propuesta del Q1"
"¿Cuántos correos de spam tengo?"
"Muéstrame el hilo de [asunto]"
"Lee la carpeta Clientes"

Comandos principales

Leer inbox (correos recientes)

gog gmail search 'in:inbox newer_than:1d' --max 20 --json
gog gmail search 'in:inbox is:unread' --max 50 --json
gog gmail search 'in:inbox newer_than:7d' --max 100 --json

Leer spam

gog gmail search 'in:spam newer_than:30d' --max 50 --json

Leer una carpeta/etiqueta específica

# Etiquetas de sistema
gog gmail search 'in:sent newer_than:7d' --max 20 --json
gog gmail search 'in:drafts' --max 20 --json
gog gmail search 'in:trash newer_than:30d' --max 20 --json
gog gmail search 'is:starred' --max 20 --json

# Etiquetas personalizadas (carpetas del usuario)
gog gmail search 'label:Clientes newer_than:30d' --max 20 --json
gog gmail search 'label:Proyectos' --max 20 --json
gog gmail search 'label:Facturas newer_than:90d' --max 20 --json

Buscar correos

# Por remitente
gog gmail search 'from:[email protected] newer_than:30d' --max 20 --json

# Por asunto
gog gmail search 'subject:propuesta' --max 10 --json

# Por contenido
gog gmail search 'propuesta presupuesto 2026' --max 10 --json

# Combinado
gog gmail search 'from:[email protected] is:unread newer_than:7d' --max 10 --json

# Con adjuntos
gog gmail search 'has:attachment in:inbox newer_than:7d' --max 10 --json

Filtros de tiempo útiles

Filtro	Significado
`newer_than:1d`	último día
`newer_than:7d`	última semana
`newer_than:30d`	último mes
`older_than:180d`	más de 6 meses
`after:2026/01/01`	desde fecha exacta

Presentación de resultados

Después de obtener el JSON, presenta un resumen claro al usuario:

📥 INBOX — 8 correos nuevos (3 no leídos)

  ⭐ [hoy 09:14] [email protected]
     "Reunión urgente esta tarde"

  📧 [hoy 08:30] [email protected]
     "Re: Propuesta Q1 2026"

  📰 [ayer 18:00] [email protected]
     "Top 10 AI tools this week"
  ...

¿Quieres que analice estos correos o que responda alguno?

Múltiples cuentas

Si el usuario tiene más de una cuenta de Gmail:

# Listar cuentas configuradas
gog auth list

# Leer de una cuenta específica
gog gmail search 'in:inbox is:unread' --account [email protected] --max 20 --json

# Cambiar cuenta por defecto
export [email protected]

Notas importantes

Usar siempre --json para obtener datos estructurados
Usar --no-input en modo automático/cron para evitar prompts interactivos
El flag --max limita resultados; aumentar si el usuario quiere más
Los resultados de búsqueda de Gmail usan la misma sintaxis que gmail.com

Usage Guidance

What to check before installing/using this skill: 1) Fix/inspect metadata: the registry shows 'Required env vars: [object Object]'. Confirm the skill will request only the env vars you expect (GOG_ACCOUNT; optionally ANTHROPIC_API_KEY and NOTIFY_CHANNEL). Ask the publisher to correct the package metadata. 2) Inspect the brew tap before installing: the formula comes from steipete/tap. Review the tap/formula repository (and gog CLI source) so you trust the binary you're installing. 3) OAuth credentials: the skill requires you to provide Google OAuth credentials (client_secret.json) and run gog auth. Keep that credentials file private and follow Google best practices. Be careful where you store it and who you grant file permissions to. 4) External AI API: the analyzer and responder use Anthropic (ANTHROPIC_API_KEY) to process email contents unless privacy_mode is enabled. Only provide that API key if you are comfortable with email content being sent to that external service; enable privacy_mode (or anonymize sensitive content) if you prefer. 5) Confirm destructive and automated actions: email-organizer includes destructive commands (trash/delete) but the docs mandate explicit confirmation. Before enabling scheduled cron/heartbeat jobs or allowing the agent to run automatically, confirm whether enabling is manual. Do not enable automatic background jobs or notification channels until you understand what will run and when. 6) Audit/logs and exports: the skill saves audit logs and detected prompts to files in ~/.openclaw/workspace and can export data to Google Sheets via gog sheets (requires SHEET_ID/credentials). If you want privacy, verify where logs are stored and consider enabling privacy_mode. 7) Test in a controlled environment: try read-only queries first (search/get) and avoid granting send/delete permissions until satisfied. Ask the skill author whether any install step will write to OpenClaw config files automatically or only provide instructions for you to apply. If you want, I can produce a short checklist of specific commands and files to inspect (brew formula URL, gog binary SHA, openclaw config diffs) before installing.

Capability Analysis

Type: OpenClaw Skill Name: gmailcleaner Version: 1.0.0 The OpenClaw email skill bundles provide legitimate email management functionality using the `gog` CLI and Anthropic AI. While they include powerful and sensitive capabilities (email deletion, sending, automation, Google Sheets/Docs access), they also incorporate strong safeguards by explicitly instructing the OpenClaw agent to *always* seek user confirmation before executing destructive or sending actions. However, a significant vulnerability exists in how the agent is instructed to construct `gog gmail search '<query>'` commands from user input (e.g., in `email-reader-SKILL.md`, `email-organizer/SKILL.md`, `email-responder/SKILL.md`). Without explicit sanitization of user-provided `<query>` parameters before passing them to the shell, this creates a **shell injection (RCE) vulnerability**, allowing a malicious user to execute arbitrary commands via the `gog` CLI. This is a critical flaw that allows attacks, classifying it as suspicious rather than malicious due to the lack of clear evidence of intentional harmful behavior from the skill itself.

Capability Assessment

ℹ Purpose & Capability

The name/description (Gmail reader/manager) match the runtime instructions: all commands use the gog CLI and the documented env vars (GOG_ACCOUNT, ANTHROPIC_API_KEY for analyzer/responder, NOTIFY_CHANNEL for scheduler) make sense for the listed features. However, the registry-level 'Required env vars' field is malformed ([object Object]) which is inconsistent with the SKILL.md files and suggests a metadata/packaging error that should be fixed.

⚠ Instruction Scope

The SKILL.md instructions go beyond simple read-only queries: they show how to configure OAuth credentials (client_secret.json), read and write local OpenClaw files (~/.openclaw/openclaw.json, HEARTBEAT.md, ~/.openclaw/workspace/email_audit.log, prompts_log.md), and set up cron/heartbeat jobs and notification channels. Organizing/deleting commands include examples of destructive batch operations (trash/delete) — the organizer doc mandates user confirmation, but the skill's ability to create scheduled automation and write configs means it can enable persistent background actions. The analyzer/responder parts also instruct sending email content to an external AI service (Anthropic) unless privacy_mode is enabled. These behaviors are within the skill's purpose but increase impact and require explicit user consent and careful configuration.

ℹ Install Mechanism

Install uses a Homebrew formula: steipete/tap/gogcli which produces the gog binary. A brew tap is a standard install path; however it is a third-party tap (not the main Homebrew core). This is a moderate-risk install source compared with an official project/tap — you should inspect the tap/formula source before installing.

⚠ Credentials

Requested environment/config access in SKILL.md (GOG_ACCOUNT, optional ANTHROPIC_API_KEY, NOTIFY_CHANNEL) is justified by the skill features. Concerns: (1) SKILL registry metadata is malformed and doesn't clearly list the required env vars; (2) the skill requires OAuth client credentials (client_secret.json) and instructs running 'gog auth credentials /path/to/client_secret.json' — that requires access to a local secrets file; (3) analyzer/responder will send email content to an external AI API (Anthropic) unless privacy_mode is enabled, so providing that API key allows email contents to be sent to a third-party. These are proportionate only if you knowingly provide them.

ℹ Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges, but it documents how to add cron jobs and heartbeat entries (scheduled background checks and notifications) and to write audit logs and prompt-detection logs. That gives it a persistent effect once enabled. The SKILL.md generally recommends confirmations for destructive actions and asks the user before activating scheduled jobs, but you should confirm whether the agent or the install routine will modify configs automatically or only provide instructions.

Version History

v1.0.0

Major update: The skill has been rebranded and expanded for comprehensive Gmail reading via the gog CLI. - Renamed from "gmailcleaner" to "email-reader" and upgraded to version 2.0.0. - Now supports reading emails from all Gmail folders and labels, not just cleaning. - Details initial setup steps and provides commands for inbox, spam, custom labels, and search. - Includes guidance for multiple account management and using powerful search filters. - Clear instructions for presenting email summaries to users.

Metadata

Slug gmailcleaner

Version 1.0.0

License —

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is gmailcleaner?

Reads emails from Gmail (all folders/labels) using the gog CLI. Use when the user asks to check email, read inbox, show unread messages, list folders, search... It is an AI Agent Skill for Claude Code / OpenClaw, with 441 downloads so far.

How do I install gmailcleaner?

Run "/install gmailcleaner" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is gmailcleaner free?

Yes, gmailcleaner is completely free (open-source). You can download, install and use it at no cost.

Which platforms does gmailcleaner support?

gmailcleaner is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created gmailcleaner?

It is built and maintained by Coorops25 (@coorops25); the current version is v1.0.0.

More Skills

gmailcleaner