Gws Gmail Watch

Gmail: Watch for new emails and stream them as NDJSON.

Security Scan

The skill's declared purpose (watch Gmail and stream messages) matches the instructions, but it hides important auth/credential and dependency details in an external shared SKILL.md and does not declare the Google/GCP credentials or config access it implicitly needs.

Purpose & Capability

The skill is instruction-only and simply invokes the 'gws' CLI to watch Gmail and stream NDJSON, which aligns with the name/description. Requiring the 'gws' binary is expected for this purpose.

Instruction Scope

SKILL.md explicitly directs the agent to read ../gws-shared/SKILL.md for auth, global flags, and security rules. That external file likely contains authentication steps and possibly references to credentials or config paths — a hidden dependency not included here. The instructions also create/use GCP Pub/Sub resources (topic/subscription) which imply access to GCP IAM and Gmail push configuration even though those details are not surfaced.

Install Mechanism

There is no install spec and no code files — lowest-risk delivery model. The only runtime requirement is that a 'gws' binary exists on PATH; the skill does not itself download or execute additional artifacts.

Credentials

The skill operates on Gmail and GCP Pub/Sub but declares no required environment variables or primary credential. Because it references another SKILL.md for auth, required credentials (Google OAuth tokens, service account keys, GCP project credentials) are hidden rather than declared, which is disproportionate and opaque.

Persistence & Privilege

The skill is not always-enabled and does not request persistent presence or elevated platform privileges. It does have options to create persistent GCP Pub/Sub resources, but that behavior is controlled by flags (e.g., --cleanup) and is within the user's control.

What to consider before installing

This skill appears to just wrap a 'gws' CLI command to watch Gmail, but it hides its authentication steps in a referenced ../gws-shared/SKILL.md that is not included. Before installing or running it: 1) inspect the referenced gws-shared SKILL.md to see exactly how auth is performed and where credentials/config are stored; 2) verify the provenance and integrity of the 'gws' binary (where it comes from and what permissions it requires); 3) confirm what Google/GCP credentials or service account scopes are needed (Gmail API, Pub/Sub publisher/subscriber) and grant only least privilege; 4) be cautious about Pub/Sub resources left behind — prefer using --cleanup or a disposable project/account for testing; 5) if you cannot review the shared auth file or trust the gws binary source, do not install or run this skill.

gmail +watch

PREREQUISITE: Read ../gws-shared/SKILL.md for auth, global flags, and security rules. If missing, run gws generate-skills to create it.

Watch for new emails and stream them as NDJSON

Usage

gws gmail +watch

Flags

Flag	Required	Default	Description
--project	—	—	GCP project ID for Pub/Sub resources
--subscription	—	—	Existing Pub/Sub subscription name (skip setup)
--topic	—	—	Existing Pub/Sub topic with Gmail push permission already granted
--label-ids	—	—	Comma-separated Gmail label IDs to filter (e.g., INBOX,UNREAD)
--max-messages	—	10	Max messages per pull batch
--poll-interval	—	5	Seconds between pulls
--msg-format	—	full	Gmail message format: full, metadata, minimal, raw
--once	—	—	Pull once and exit
--cleanup	—	—	Delete created Pub/Sub resources on exit
--output-dir	—	—	Write each message to a separate JSON file in this directory

Examples

gws gmail +watch --project my-gcp-project
gws gmail +watch --project my-project --label-ids INBOX --once
gws gmail +watch --subscription projects/p/subscriptions/my-sub
gws gmail +watch --project my-project --cleanup --output-dir ./emails

Tips

• Gmail watch expires after 7 days — re-run to renew.
• Without --cleanup, Pub/Sub resources persist for reconnection.
• Press Ctrl-C to stop gracefully.

See Also

• gws-shared — Global flags and auth
• gws-gmail — All send, read, and manage email commands