Menu
Use when managing Gmail messages, labels, or email workflows via gws CLI or Gmail MCP tools
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when constructing or interpreting the approval handoff envelope between subagent and orchestrator -- sealed_payload schema, approval_id format, APPROVAL_REQUEST contract shape, and reading a granted approval from the DB
Use when producing any agent response
Use when classifying any operation before executing it, or deciding whether user approval is required
Use when a mutative command was blocked by the hook and you need to request user approval, or when presenting a plan for a T3 operation before executing it
Use when the user wants to build, design, or extend a diagram — an architecture overview, a timeline, a planner board, a flow diagram, a presentation, a comparison, or a mind-map — as a portable, data-driven deck rendered from plain YAML. Triggers — "build a diagram", "architecture diagram", "diagram deck", "timeline", "flow diagram", "planner board", "add a page/section/component to the diagram".
Use when the user wants something to run routinely / on a schedule rather than once now -- "tarea programada", "rutinariamente", "cada mañana", "cada N horas", "todas las noches", "schedule", "cron". Covers mounting, structuring, and running an unattended headless task that reports back, plus consuming its reports. NOT for a live in-session agentic loop (that is agentic-loop).
| name | gmail-policy |
| description | Use when managing Gmail messages, labels, or email workflows via gws CLI or Gmail MCP tools |
| metadata | {"user-invocable":false,"type":"technique"} |
The most common mistake is treating every email-related request as an execution command. Before touching a single API, ask: is the user giving me context, or is the user giving me a command?
This is a reasoning step, not a checklist. Run it silently before every response.
| Lo que dice el user | Intent real | Acción correcta |
|---|---|---|
| "necesito analizar un correo y enviar unos correos importantes" | Contexto -- está contándote el plan, no ejecutando | No hacer nada de envío; esperar el comando específico |
| "chequea mis correos y ve si hay algo importante" | Review + iniciativa concedida | Leer inbox, triage, generar drafts para los que merezcan respuesta, presentar lista al user |
| "dile que aceptamos y envíaselo" | Comando explícito de envío | Crear y enviar directamente (un solo ciclo T3, no draft→send) |
| "mándale un correo a X diciéndole Y" | Ambiguo | Preguntar: ¿quiere draft para revisar o envío directo? |
| "respóndele a Assetplan aceptando" | Ambiguo, tendencia a draft | Default a draft si el contenido involucra datos personales, decisiones comerciales, o formularios |
| "dile que llego a las 5pm" | Comando simple, contenido reversible | Envío directo está bien sin pasar por draft |
| "prepara una respuesta para X" | Draft explícito | Crear draft y reportar |
There is no fixed pipeline where every send goes through draft→approve→send. That workflow exists as a safety net for sensitive cases, not as the default for every email. When the user says "envíaselo", they mean send -- one T3 approval, one action, done.
The question is not "should I always draft first?" The question is: what did the user actually ask for, and how reversible is this action?
If you're uncertain, ask once. Do not silently choose draft when the user said send.
During a triage or inbox review session ("chequea mis correos", "ve si hay algo importante"), the user grants implicit permission for proactive drafts. You do not need to ask for approval before creating each one.
Pattern:
The user reviews and approves individual drafts before sending. The generation step does not require one-by-one confirmation -- the presentation step does.
Do not generate drafts proactively outside triage context. If the user opens a conversation about a single email, default to their explicit instruction.
| Scenario | Default action |
|---|---|
| User says "envíaselo" / "mándalo" / "dile que sí y envíaselo" | Send direct -- T3 approval for send, not for draft then send again |
| User says "prepara una respuesta" / "redacta" | Draft |
| Reply contains PII (RUT, cuenta bancaria, dirección, DOB) | Draft even if user said "mándale" -- confirm before send |
| Reply is a business commitment (arrendamiento, contrato, formulario) | Draft unless user explicitly says send |
| Simple logistics (hora, confirmación de asistencia, "llegaré tarde") | Direct send fine |
| Ambiguous command + first time with this recipient | Ask once |
When you do create a draft, verify it with gws gmail users drafts list and report the draft ID and snippet to the user. This closes the loop.
Before asking the user for a datum (RUT, dirección, cuenta bancaria, etc.), check these sources in order:
~/Documents/personal/**/data.json, spreadsheetsWhen you find data in another thread, cite the source: "Tu RUT lo saqué de un correo de Colmena del 2024-03." This builds trust and shows the search was real.
Any .eml or temporary file containing PII (RUT, cuenta bancaria, teléfono, DOB, dirección) must be deleted with rm after the draft is created. Verify deletion with Glob or ls. Report: "Archivo temporal eliminado."
| Operation | Tier | Notes |
|---|---|---|
gws gmail users messages list | T0 | Search/filter messages |
gws gmail users messages get | T0 | Read message content |
gws gmail users labels list | T0 | List available labels |
gws gmail users labels get | T0 | Read label details |
gws gmail +search | T0 | Macro search (syntactic sugar over list) |
gws gmail users messages modify --addLabelIds | T0 | Add any _gaia/* label (non-destructive) |
gws gmail users messages modify --removeLabelIds | T2 | Changes message visibility |
gws gmail users messages modify (action→waiting after send) | T2 | Auto-transition after user reply -- logged, no approval |
gws gmail users drafts create | T3 | Creates draft on user's behalf |
gws gmail users drafts list | T0 | Verify draft was created |
gws gmail +reply --message-id --body | T3 | Sends reply on user's behalf |
gws gmail users messages send --params | T3 | Sends/replies via raw RFC 2822 |
gws gmail users labels create | T3 | Creates new label |
Permanently denied by the hook -- gmail.modify OAuth scope excludes delete at the API level.
| Operation | Reason |
|---|---|
gws gmail users messages delete | Permanent, unrecoverable |
gws gmail users messages trash | Moves to trash (use _gaia/trash label instead) |
gws gmail users messages purge | Permanent purge |
gws gmail users drafts delete | Draft deletion |
gws CLI exposes convenience macros prefixed with + (e.g. +reply, +send, +search). The hook strips the leading + before the verb taxonomy lookup inside detect_mutative_command(), so each macro classifies like its base verb:
gws gmail +reply → token reply → match in MUTATIVE_VERBS → T3 blockgws gmail +send → token send → match in MUTATIVE_VERBS → T3 blockgws gmail +search → token search → match in READ_ONLY_VERBS → safeFix applied 2026-04-17 in hooks/modules/security/mutative_verbs.py after a +reply invocation slipped through as "safe by elimination" during a Gmail session.
+reply vs send --params| Use case | Command | Pros | Cons |
|---|---|---|---|
| Simple plaintext reply | gws gmail +reply --message-id <id> --body "<text>" | Simple, handles threading headers automatically | Plaintext only, no HTML, no collapsed quote, no signature |
| HTML reply with signature + collapsed quote | gws gmail users messages send --params '{"userId":"me","threadId":"<tid>","raw":"<base64url>"}' | Full control over MIME, looks native in Gmail | Must construct RFC 2822 manually and base64url-encode |
Use +reply for quick operational replies where formatting does not matter. Use send --params when the recipient will see the mail in a mail client and visual quality matters.
For the correct gws gmail users drafts create schema, RFC 2822 template, base64url encoding pipeline, and other technical patterns -- see reference.md in this skill directory.
_gaia/*)| Label | Purpose | Lifecycle |
|---|---|---|
_gaia/action | I need to do something (respond, pay, read) | Clears when user acts → moves to waiting or removed |
_gaia/waiting | I already acted, waiting for the other party | Clears when other party responds → back to action or removed |
_gaia/someday | Interesting but no urgency (promos, articles, ideas) | Resurfaces in weekly review, user clears manually |
_gaia/pending | Staging area during mass triage | Empties during triage sessions |
_gaia/trash | Soft delete | Accumulates, user reviews |
No _gaia/* label = processed/done. No extra label needed.
inbox ──→ action (user or AI: I need to act)
inbox ──→ waiting (AI detects user already replied in thread)
inbox ──→ someday (user defers, no urgency)
inbox ──→ trash (not wanted)
inbox ──→ pending (mass triage staging)
action ──→ waiting (user replied/acted → auto T1 transition)
action ──→ done (handled, no follow-up → remove label)
action ──→ someday (user defers)
waiting ──→ action (other party replied → needs user attention)
waiting ──→ done (resolved → remove label)
someday ──→ action (user decides to act)
someday ──→ trash (not worth it)
someday ──→ done (reviewed, no action needed → remove label)
pending ──→ {action, waiting, someday, trash, done} (triage output)
When an email contains a specific date/time deadline (bill due date, event, appointment): create a calendar event AND label the email _gaia/action. The calendar is the time-trigger; the label is the state-tracker.
| Category | Labels |
|---|---|
| Finance | Finance/Bank, Finance/Transfers, Finance/Insurance |
| Jobs | Jobs/Alerts, Jobs/Academic |
| Shopping | Shopping/Promos, Shopping/Orders |
| Music | Music/Nucleo, Music/DJ |
| Social | Social/LinkedIn, Social/Facebook |
| Services | Services/Subscriptions, Services/Utilities |
| Tech | Tech/Programming, Tech/SalesForce |
| Personal | Personal/Notes, Personal/Travel, Personal/Downloads |
| Legacy | _gaia/legacy -- retired: Buzz!!, Isercon, WaReS, +1, multi-forward, GDrive, PokerStar |
Use gmail.modify scope (read + label + move, no delete). Full access scope (https://mail.google.com/) is blocked -- it includes delete permissions that bypass both hook and label controls.
gmail-triage -- interactive triage workflowgws-setup -- CLI installation and authentication