Skip to content
Get packs

Guide · Agent skill

How to use the Gmail New-Mail Watcher agent skill (gws-gmail-watch)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The gws-gmail-watch skill teaches an AI agent to use the gws command-line tool to watch a Gmail account for new messages and print each one as a line of JSON (NDJSON). This guide explains what a skill is, how to install this one, how to ask for it in plain language, and what you need before it works. By the end you will be able to run a Gmail watch from an agent and know the main flags and safety points.

Gmail New-Mail Watchergoogleworkspace/cli · Apache-2.0

Quick start

  1. 1Check prerequisites. Confirm the gws tool is installed, your Google Cloud project has Pub/Sub enabled, and your Google account is authenticated through gws-shared.
  2. 2Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Make sure gws-shared exists. If the gws-shared SKILL.md file is missing, run gws generate-skills to create it.
  4. 4Ask for the watch. Describe what you want in plain language, such as watching INBOX for new unread messages.
  5. 5Run with a label filter. Use --label-ids to limit results, for example INBOX,UNREAD, and --once for a single pull.
  6. 6Save output if needed. Add --output-dir to write each message to its own JSON file for later processing.
  7. 7Stop and clean up. Press Ctrl-C to stop. Add --cleanup if you want created Pub/Sub resources deleted on exit.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. When the task comes up, the agent reads the file and follows it. This skill covers one command, gws gmail +watch, rather than being a standalone app.

With the skill loaded, the agent can watch a Gmail account for new messages and stream each one as a line of JSON. It can filter by Gmail label IDs, write each message to its own file, and set up or reuse Google Cloud Pub/Sub resources, which Gmail uses to push notifications.

What do you need before installing?

The skill assumes several pieces are already in place. Check these first, because the watch will not start without them.

  • The gws command-line tool (googleworkspace CLI).
  • A Google Cloud project with Pub/Sub enabled and Gmail push permission granted on the topic. Setup needs GCP Pub/Sub permissions.
  • An authenticated Google account set up through the gws-shared auth flow.
  • The shared gws-shared SKILL.md file. If it is missing, run gws generate-skills to create it.

How do you install the skill?

Download the ZIP from the skill page on this site and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of two places:

  • Personal use across projects: ~/.claude/skills/
  • One project only: .claude/skills/ inside the project folder
  • Claude apps: upload the ZIP under Settings → Capabilities → Skills

How do you trigger the skill with a request?

You do not need to type the command yourself. Ask the agent in plain language about new Gmail messages, and it should pick up the skill because its description covers watching Gmail for new emails. Be specific about what you want: the label, whether to run once, and where to save the output.

Example requests you could make:

  • Watch my Gmail inbox for new unread messages and print each one as JSON.
  • Run the Gmail watcher once on INBOX and show me what arrived.
  • Stream new emails into ./emails as one JSON file per message.

What are the main flags and examples?

The command takes these flags. Only the Pub/Sub setup flags and the output options are most often needed.

  • --project: GCP project ID for Pub/Sub resources.
  • --subscription: an existing Pub/Sub subscription name, which skips setup.
  • --topic: an existing Pub/Sub topic with Gmail push permission already granted.
  • --label-ids: comma-separated Gmail label IDs to filter, such as INBOX,UNREAD.
  • --max-messages: maximum messages per pull batch (default 10).
  • --poll-interval: seconds between pulls (default 5).
  • --msg-format: full, metadata, minimal or raw (default full).
  • --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.
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

What should you know about safety?

This skill runs scripts and uses the network. The watch streams full message content by default, so anything it prints or writes can contain private data. Choose the --msg-format and --output-dir options deliberately, and avoid sending streamed output to shared logs when the mailbox is sensitive.

The skill only watches for new messages. It does not send or manage email. For those commands, see the gws-gmail skill. Read the gws-shared SKILL.md for auth, global flags and security rules before running anything.

What tips help the watch run smoothly?

A few behaviours in the source affect how you run the watch.

  • Gmail watch expires after 7 days, so re-run the command to renew it.
  • Without --cleanup, Pub/Sub resources persist, which lets you reconnect later.
  • Press Ctrl-C to stop the watch gracefully.

What people use it for

  • Triage new inbox mail by streaming INBOX messages as JSON into a processing pipeline.
  • Save each incoming message to its own file in a folder for later analysis.
  • Run a one-off pull with --once to check what arrived since the last check.
  • Reconnect to existing Pub/Sub resources by passing --subscription or --topic instead of creating new ones.

Frequently asked questions

Is the gws-gmail-watch skill free?

The source does not state pricing or licence terms for the skill beyond the listed licence, Apache-2.0. Google Cloud and Pub/Sub usage may have its own costs, so check your Google Cloud account before setup.

How do I install the gws-gmail-watch skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What do I need to run gmail +watch?

You need the gws command-line tool, a Google Cloud project with Pub/Sub enabled and Gmail push permission on the topic, an authenticated Google account, and the gws-shared SKILL.md file. If that file is missing, run gws generate-skills.

Why does my Gmail watch stop working?

The source says a Gmail watch expires after 7 days, so you need to re-run the command to renew it. Use Ctrl-C to stop it gracefully when you are finished.

Can this skill send emails?

No. The skill only covers watching for new messages. For sending and managing email, the source points to the gws-gmail skill.

How is this different from the gws-gmail skill?

gws-gmail-watch covers only watching for new messages and streaming them as NDJSON. The gws-gmail skill covers all send, read and manage email commands.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run the gws tool with Google Cloud set up and want an agent to react to incoming Gmail as JSON. Pick something else if you lack a Google Cloud project, need to send or manage email, or work with a mailbox where streaming full message content would expose private data.

Download the skill