gmail-cleanup

Generated source view for the actual executable productivity/gmail-cleanup skill. The durable routing article is Google Workspace Skills. Source: skills/productivity/gmail-cleanup/SKILL.md

Runtime Source

Bundled Resources

These files are part of the executable skill folder and must be preserved with the skill source.

Description

Keep Kevin's personal Gmail organized with gws: label taxonomy, archiving stragglers, trashing old codes and notifications, handling promotions. Dry-run by default, weekly via launchd. Use on "clean up my inbox", "gmail cleanup" or rule edits.

Skill Source

---
name: gmail-cleanup
description: >-
  Keep Kevin's personal Gmail organized with gws: label taxonomy, archiving stragglers, trashing
  old codes and notifications, handling promotions. Dry-run by default, weekly via launchd. Use on
  "clean up my inbox", "gmail cleanup" or rule edits.
origin: personal
source_slug: gmail-cleanup
metadata:
  openclaw:
    category: "productivity"
    requires:
      bins:
        - gws
        - python3
---

# Gmail Cleanup

This skill is intentionally a thin router. The durable behavior lives in `scripts/` and the policy
lives in `references/mailbox-taxonomy.md`. Do not turn the deterministic cleanup rules into prompt
text; change the script and the reference together.

## Prerequisites

1. `gws` on `$PATH` (`brew install googleworkspace-cli`) and authenticated (`gws auth status`).
   Read `../gws/references/skills/gws-shared/SKILL.md` for auth, flags, and security rules.
2. First-time or expired auth: `bash scripts/auth-setup.sh` runs `gws auth login` with the Gmail
   scopes, verifies the profile, dry-runs the policy, and installs the launchd job. The Desktop
   OAuth client "gws CLI (gmail-cleanup)" already exists on project Kevin-Wiki
   (nimble-willow-457719-s5) and its consent screen is In production, so tokens do not expire on
   the 7-day Testing schedule; if `~/.config/gws/client_secret.json` is missing the script prints
   how to recreate it. Kevin clicks the Google consent screen himself; never automate Google login.

## Commands

```bash
skill_dir="${CLAUDE_SKILL_DIR:-${CODEX_SKILL_DIR:-skills/productivity/gmail-cleanup}}"
[ -d "$skill_dir" ] || skill_dir=".agents/skills/gmail-cleanup"

python3 "$skill_dir/scripts/gmail_maintenance.py"                 # DRY RUN: count what each rule would touch
python3 "$skill_dir/scripts/gmail_maintenance.py" --apply         # apply the standing policy, write a JSON receipt
python3 "$skill_dir/scripts/gmail_maintenance.py" --only trash-   # run a subset (rule id prefixes)
bash    "$skill_dir/scripts/install-launchd.sh"                   # weekly schedule (Sun 09:15) via launchd
bash    "$skill_dir/scripts/install-launchd.sh" --status          # is it loaded, last receipts
```

Receipts land in `~/Library/Logs/gmail-cleanup/` (never in the wiki tree). Report the receipt path
and the per-rule counts back to Kevin.

## Procedure for an agent-led run

1. `gws auth status`. If unauthenticated, stop and hand Kevin `scripts/auth-setup.sh`.
2. Dry run. Read the counts. If any trash rule is near the `--max-trash` guard, investigate before
   applying; a spike usually means a filter or label rule regressed.
3. Apply only after the dry run looks like the policy in `references/mailbox-taxonomy.md`.
4. Spot-check with live searches (`gws gmail users messages list --params '{"userId":"me","q":"in:inbox label:\"Social Media/LinkedIn\""}'`), not with Gmail's category tab counters, which lag for hours.
5. Log a one-line entry in `wiki/log.md` only when the policy itself changed, not for routine runs.

## Changing the policy

- New sender family: add a filter (edit `assets/mailFilters.xml`, import in Gmail Settings > Filters
  with "apply to existing"), then add the label to the right list in `scripts/gmail_maintenance.py`.
- New label that must never be trashed: add it to `PROTECTED_LABELS` in the script first.
- Promotions are kept by decision (2026-09-24). Trashing promotions older than a year is opt-in via
  `--trash-old-promos` and must be asked for explicitly each time.

## Hard rules

- Never permanently delete, never empty Trash, never unsubscribe, never send mail from this skill.
- Never automate Google login or paste OAuth secrets into chat or logs.
- Prefer the gws API path. The Gmail web UI fallback in `references/mailbox-taxonomy.md` exists only
  for when the API is unavailable; it is slow and throttled.

## Related Skills

- `gws` (router) and its `gws-gmail`, `gws-gmail-triage`, `gws-shared` references for raw CLI usage.
- `cleanup-terminals-browsers` for the same thin-router-over-scripts convention.

---

Timeline

• 2026-11-02 | Generated a browseable source page from the actual executable skill file. Source: skills/productivity/gmail-cleanup/SKILL.md