gmail-labeler

Gmail inbox triage, labeling, and safe archiving with gog plus a configurable lightweight LLM review layer. Use when building or running Gmail automation tha...

Security Scan

The skill's declared requirements and install steps do not match its runtime behavior: it expects secrets and a secrets-fetch tool (doppler) and an env var for gog account but does not declare them, which is a concerning mismatch you should resolve before trusting it with Gmail access.

Purpose & Capability

The skill claims to be a Gmail triage/labeler using 'gog' and an optional lightweight LLM review. That general purpose matches the included Python runner and filters. However, the skill fails to declare several capabilities it actually relies on: the launcher fetches GOG_KEYRING_PASSWORD via the 'doppler' CLI and the default config references an account environment variable (GOG_ACCOUNT). Those are necessary for Gmail access but are not listed under required binaries or required env vars.

Instruction Scope

SKILL.md and the scripts largely stay within expected scope (classify, label, log, keep private overlays outside the repo). But the provided launcher script explicitly calls 'doppler secrets get' to fetch GOG_KEYRING_PASSWORD and then runs the Python runner. SKILL.md does not document or declare Doppler usage or the env var names the runner will read. The runner also writes logs outside the skill tree and expects a local overlay config path — those behaviors are reasonable for this tool but increase the environment/secret surface and should be declared.

Install Mechanism

The install spec pulls an npm package (@felipematos/ain-cli) to provide an 'ain' binary for structured LLM review. Using an npm package for an optional review helper is plausible. This is a moderate-risk install mechanism (npm packages are not pre-reviewed by the platform), but the package source is an identifiable npm name rather than an arbitrary download URL. The skill does not declare Node or npm as required binaries, which is an omission.

Credentials

The published metadata lists no required env vars or credentials, yet: 1) default-config.json sets accountEnv: 'GOG_ACCOUNT' (so the runner expects an env var for account selection), 2) the launcher uses 'doppler secrets get GOG_KEYRING_PASSWORD' to retrieve a keyring password, and 3) the LLM review section names providers/models (including cloud models) but does not declare any provider API keys. The skill therefore requests or depends on secrets and tooling that are not declared, which is disproportionate and a security concern.

Persistence & Privilege

The skill is not marked always:true and does not request special permanent platform privileges. It writes logs and reads a local overlay (recommended to be outside the skill directory) but does not appear to modify other skills or request global agent configuration changes in the provided files.

What to consider before installing

This skill implements plausible Gmail triage logic, but it has important undeclared dependencies and secret-handling behavior you should verify before installing. Actionable steps: - Expect to provide Gmail access credentials (gog account/token). The default config uses GOG_ACCOUNT and the launcher expects a GOG_KEYRING_PASSWORD; these env vars/secrets should be explicitly declared and reviewed. - The launcher script calls 'doppler'. If you don't use Doppler, edit the launcher or provide the key by another safe mechanism; do not run the provided script as-is unless you trust the Doppler project/configuration it references. - The install pulls an npm package (@felipematos/ain-cli) for LLM review. Decide whether you trust that package and whether you want Node/npm installed on the agent host. - LLM review can require provider API keys (not declared). If you enable the LLM layer, make sure provider credentials are stored locally/outside the skill and that the skill is configured to use them explicitly. - Run in dry-run mode on a non-production account first and inspect logs (they are written outside the skill folder by default) to confirm no unexpected outbound endpoints or secret exfiltration. - To improve confidence, ask the skill author to: (1) declare required binaries (gog, python3, doppler, node/npm if applicable), (2) list required env vars (GOG_ACCOUNT, GOG_KEYRING_PASSWORD or how to supply it), and (3) document any LLM provider credential expectations. If you cannot obtain those clarifications, treat the skill as risky for production Gmail accounts.

A production-oriented Gmail labeling workflow built around:

• gog for Gmail access
• a local overlay for private rules/accounts/routes
• a hybrid review flow: heuristics first, lightweight LLM review for ambiguity-band messages
• a 15-minute cron-friendly runner

What it does

• Classifies inbox items into non-actionable vs actionable buckets
• Applies Gmail labels and archives non-actionable mail
• Keeps replies, opportunities, urgent billing items, and other actionable mail in Inbox
• Supports English, Portuguese, and Spanish keyword coverage out of the box
• Logs every decision to JSONL for auditability and tuning
• Purges logs older than 30 days
• Supports a daily self-improvement review loop based on prior decisions and user corrections

Default categories

Non-actionable

• Newsletters
• Promotions
• Notifications
• Ordinary receipts

Actionable

• Billing issues
• Replies
• Opportunities
• Action Required

What stays local/private

Keep user-specific editorial, business, or inbox-policy rules in the local overlay, not in the shared skill defaults. Examples of local-only rules:

• PR / press release handling
• press trip or media invitation routing
• VIP sender policies
• business-specific labels
• custom notification routes

Operating model

1. Sender-type-first routing

Classify sender as:

• person
• company
• person_or_unknown

This keeps bulk automated mail cheap to classify and reserves deeper review for ambiguous or human-origin messages.

2. Inbox-by-exception policy

Treat Inbox as an action queue, not a reading queue. Recommended default:

• processed mail always gets Auto/Triaged
• mail stays in Inbox only when it is clearly actionable / important
• everything else should leave Inbox, even when the category is still somewhat generic

Practical effect:

• important/actionable mail → keep in Inbox and add category labels when possible
• non-important mail → remove INBOX, keep Auto/Triaged, then add a best-fit category label (Notification, Newsletter, Receipt, Press Releases, etc.)

3. Confidence-band review

Use heuristics first. Then send only ambiguity-band messages to a lightweight LLM review.

Recommended pattern:

• high confidence → trust heuristics
• medium confidence → LLM review
• low confidence → conservative fallback

4. Conservative-but-useful fallback

If a message is clearly automated/company-origin but no specific filter matches, prefer a generic non-actionable classification (for example Notification) over leaving it untouched in Inbox.

5. Label normalization

Use a small canonical label set and avoid near-duplicates caused by translation, singular/plural, or typos. Example normalization targets:

• Press Release → Press Releases
• finance label variants → one canonical finance label
• keep Auto/Triaged as the universal processed marker

Gmail-native labels to prefer

Use Gmail system labels when possible:

• CATEGORY_PROMOTIONS
• CATEGORY_UPDATES
• IMPORTANT
• STARRED
• INBOX

Create custom labels only when needed, for example:

• Newsletter
• Notification
• Receipt
• Opportunity
• Action Required
• Auto/Triaged

Local overlay design

Keep the skill publishable by storing private configuration outside the skill directory.

Recommended local overlay path:

~/.openclaw/local/gmail-labeler.config.json

Store private values only in the local overlay:

• email accounts
• VIP senders/domains
• notification targets
• business-specific opportunity rules
• personal/custom labels

Logging and review

Decision logs should live outside the skill source tree, for example:

/home/ubuntu/.openclaw/gmail-labeler-logs/

Recommended format:

• one JSONL file per day
• one row per decision
• separate error rows

Suggested daily review inputs:

• yesterday's decision log
• false positives / false negatives
• over-aggressive archiving
• missed billing urgency
• missed opportunities
• user-requested corrections

Files to read

• references/default-config.json
• references/config-guide.md
• references/filter-catalog.md
• references/implementation-notes.md
• references/logging-and-review.md
• references/llm-review.md
• references/cron-example.md
• references/ain-email-review.schema.json

Runners

• Main runner: scripts/gmail_labeler_runner.py
• Launcher example: scripts/gmail_labeler_run.sh

Publishing guidance

Before publishing:

• keep only generic defaults in the skill
• remove personal accounts, chat ids, private domains, and custom user rules
• keep examples generic
• document clearly that private configuration belongs in the local overlay
• keep PR / press-release handling user-specific when it reflects private editorial policy; do not publish those local heuristics by default
• validate cron/non-interactive execution via the launcher, not only via direct Python invocation