smart-email-agent

All-in-one Gmail agent for OpenClaw. Fuses email-reader, email-organizer, email-analyzer, email-responder, email-scheduler, and email-reporter into a single skill with token-optimizer integration and a self-improvement engine. Use this skill for ANYTHING email-related: checking inbox, searching messages, organizing labels, classifying/prioritizing, drafting replies, scheduling automation, generating reports, or reviewing costs. Triggers on: correo, email, inbox, bandeja, spam, draft, borrador, responder, organizar, etiquetar, archivar, informe, estadísticas, notificame, automatiza, revisar mensajes, prioriza, cuanto cuesta, presupuesto, mejora el agente. Requires: gog CLI (primary) or Gmail API Python scripts (fallback).

# Smart Email Agent v3 — Gmail All-in-One

Un solo skill que reemplaza los 6 skills del pack original.
Punto de entrada único para toda la gestión de correo.

> **Lazy loading activo:** este skill se carga completo (~500 tokens).
> NO cargues los 6 skills individuales — sería 4.800 tokens desperdiciados.

---

## PARTE 1 — LEER CORREOS (email-reader)

### Herramienta principal: `gog` CLI

```bash
# Verificar prerequisitos
which gog || echo "Instalar: npm i -g gogcli  OR  brew install gogcli"
echo $GOG_ACCOUNT  # debe estar configurado

# Autenticar si es la primera vez
gog auth add $GOG_ACCOUNT
```

### Comandos esenciales

```bash
# No leídos en inbox (acción por defecto cuando el usuario dice "revisa mi correo")
gog gmail search 'in:inbox is:unread' --max 5 --format minimal --json

# Buscar por criterio — usar sintaxis Gmail
gog gmail search 'from:juan@empresa.com newer_than:3d' --max 10 --format minimal --json
gog gmail search 'subject:factura has:attachment' --max 10 --format minimal --json
gog gmail search 'in:spam is:unread' --max 20 --format minimal --json

# Leer correo completo
gog gmail get <message_id> --format full --json

# Leer hilo completo
gog gmail thread <thread_id> --format minimal --json
```

### Operadores de búsqueda Gmail

`from:` `to:` `subject:` `label:` `is:unread` `is:starred`
`has:attachment` `newer_than:Nd` `older_than:Nd`
`in:inbox` `in:sent` `in:spam` `in:trash` `filename:ext`

### Flujo estándar de lectura

1. Verificar `gog` en PATH y `GOG_ACCOUNT` configurado
2. Construir query desde la intención del usuario (preguntar si es ambiguo)
3. Ejecutar con `--format minimal --json --max N`
4. Parsear JSON → presentar lista formateada:

```
📬 5 correos no leídos:
1. De: Juan García <juan@empresa.com> | Asunto: Propuesta Q2 | Hace 2h
   Vista previa: Hola, te mando el resumen de... | ID: msg_abc123
```

5. Ofrecer: leer completo / buscar más / actuar sobre el mensaje

### Reglas de lectura

- SIEMPRE usar `--format minimal --json --max N` (N=5 por defecto)
- Nunca mostrar JSON crudo; nunca leer contenido completo sin pedirlo
- Preservar IDs para acciones de seguimiento
- Sin resultados → confirmar criterios, sugerir términos más amplios
- Solo lectura — enviar/responder requiere la sección RESPONDER (Parte 4)
- No guardar contenido de correos en MEMORY.md salvo que el usuario lo pida

### Errores comunes

| Error | Causa | Solución |
|---|---|---|
| `gog: command not found` | gog no instalado | `npm i -g gogcli` o `brew install gogcli` |
| `GOG_ACCOUNT not set` | Variable no configurada | Pedir al usuario su email Gmail |
| Token expirado | OAuth vencido | `gog auth add <email>` |
| API error 429 | Rate limit | Esperar 60s, reintentar con backoff |

---

## PARTE 2 — ORGANIZAR (email-organizer)

### Jerarquía corporativa Corp/ (azul)

```
Corp/
├── Interno/
│   ├── Management      ← Gerencia, Directores
│   ├── Tech & Ops      ← Desarrollo, Soporte, Operaciones
│   ├── Commercial      ← Ventas, Marketing
│   ├── Admin & HR      ← Jurídica, RRHH, Contabilidad
│   └── Team            ← Resto del equipo @empresa.com
├── Partners & Clientes/
│   └── [empresa]       ← Wolkvox, Masiv, Unisanitas, Nuva, etc.
├── Proveedores/
│   └── [proveedor]     ← Google, Microsoft, AWS, etc.
└── Sistema/
    ├── DMARC
    ├── Notificaciones
    ├── Alertas
    └── No-Reply
```

### Comandos de organización con gog

```bash
# Crear etiqueta
gog gmail label create "Corp/Interno/Tech & Ops"

# Aplicar etiqueta a mensaje
gog gmail label apply <message_id> "Corp/Interno/Management"

# Mover correo (quitar INBOX + aplicar etiqueta)
gog gmail modify <message_id> --add-label "Corp/Partners & Clientes/Wolkvox" --remove-label INBOX

# Archivar (quitar INBOX sin borrar)
gog gmail modify <message_id> --remove-label INBOX

# Mover a spam
gog gmail modify <message_id> --add-label SPAM --remove-label INBOX

# Mover a papelera
gog gmail trash <message_id>

# Operación batch (múltiples IDs)
gog gmail batch-modify --ids id1,id2,id3 --add-label "Corp/Sistema/No-Reply" --remove-label INBOX
```

### Reglas de routing automático

Antes de llamar a la IA, aplicar estas reglas sin costo:

```
from_domain @empresa.com + from_name contiene [Linda, Rafael, Director] → Corp/Interno/Management
from_domain @empresa.com + from_name contiene [Tech, Dev, Soporte]      → Corp/Interno/Tech & Ops
from_domain @empresa.com                                                  → Corp/Interno/Team
from contiene noreply / no-reply / donotreply                            → Corp/Sistema/No-Reply
subject contiene DMARC / SPF / DKIM                                      → Corp/Sistema/DMARC
subject contiene alerta / alert / warning                                → Corp/Sistema/Alertas
```

Guardar y mantener estas reglas en `corp_routing_rules.json`.

### Protocolo de confirmación

NUNCA ejecutar acciones destructivas sin confirmación explícita:

```
⚠️ Pendiente de confirmación:
   → Mover 22 correos a Corp/Sistema/No-Reply
   → Eliminar etiqueta "noreply" (ya vacía)
   Esto NO borra correos, solo reorganiza etiquetas.
   ¿Confirmas? (sí/no)
```

---

## PARTE 3 — ANALIZAR Y CLASIFICAR (email-analyzer)

### Decisión de modelo ANTES de analizar

```
¿Tarea es clasificar / detectar spam / routing?
  → claude-haiku-4-5-20251001   (batch de 10-20 correos, ~$0.00009/correo)

¿Tarea es extraer tareas y fechas de correos importantes?
  → claude-haiku-4-5-20251001   (body[:800], ~$0.00015/correo)

¿El presupuesto está > 80% gastado?
  → forzar haiku para TODO, sin borradores automáticos

¿El presupuesto está > 95% gastado?
  → cero llamadas IA, solo reglas locales
```

**Opus: PROHIBIDO para tareas de email.**
**Sonnet: solo para borradores (ver Parte 4).**

### Pipeline de reducción de tokens (aplicar siempre)

```python
# 1. Pre-filtro sin IA (resolver antes de gastar tokens)
#    - Dominio en corp_routing_rules.json → etiquetar directo
#    - from en known_spam_domains.txt → spam directo
#    - message_id ya en analysis_cache → reutilizar resultado
#    Objetivo: resolver 60-70% a costo $0.00

# 2. Recortar campos al mínimo necesario
CAMPOS = {
    'clasificacion': ['from', 'subject', 'snippet[:100]'],   # ~30 tokens
    'prioridad':     ['from', 'subject', 'body[:400]'],      # ~150 tokens
    'tareas_fechas': ['from', 'subject', 'body[:800]'],      # ~250 tokens
}

# 3. Limpiar texto
def limpiar(texto, limite):
    texto = re.sub(r'<[^>]+>', '', texto)             # quitar HTML
    texto = re.sub(r'https?://\S+', '[URL]', texto)   # comprimir URLs
    texto = re.sub(r'\s+', ' ', texto).strip()
    return texto[:limite]

# 4. Batch: NUNCA menos de 10 correos por llamada
#    Esperar hasta tener 10-20 correos pendientes
BATCH_MIN = 10
BATCH_MAX = 20
```

### Prompt de análisis en batch (Haiku)

```
SYSTEM (idéntico siempre — para prompt caching):
Eres un clasificador de correos corporativos.
Analiza cada correo y devuelve SOLO JSON array. Sin texto extra.
Para cada ítem: {"idx":N,"corp_label":"...","categoria":"spam|importante|informativo|sistema|otro",
"prioridad":0-10,"es_spam":bool,"necesita_respuesta":bool,
"tiene_phishing":bool,"tareas":[],"fecha_limite":"ISO o null","razon":"máx 10 palabras"}

USER: Analiza: [JSON array de hasta 20 correos con from+subject+snippet[:100]]
```

### Presentación de resultados

```
🤖 Análisis — 47 correos procesados
⚡ Sin IA (pre-filtro): 31  (66%) → $0.000
🧠 Con Haiku (2 batches): 16     → $0.006

📊 Resultado:
  🔵 Corp/Interno/Management:   2  (prioridad alta)
  🔵 Corp/Partners & Clientes:  8
  🔵 Corp/Sistema/No-Reply:    14
  🗑️  Spam:                    12
  ⚠️  Phishing detectado:        1  → ALERTA
  📋 Con tareas pendientes:      4

Críticos:
  [10/10] linda@empresa.com — "Aprobación contrato urgente"
          Tarea: confirmar antes del viernes
```

---

## PARTE 4 — RESPONDER Y REDACTAR (email-responder)

### Cuándo usar Sonnet vs Haiku para borradores

```
Prioridad >= 8 → claude-sonnet-4-6       (calidad importa)
Prioridad 5-7  → claude-haiku-4