Guide · Agent skill

How to use the gws-events-subscribe agent skill: Google Workspace events

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

The gws-events-subscribe skill teaches an AI agent to use the gws command-line tool to listen for changes in Google Workspace, such as new messages in a Google Chat space. It is aimed at developers building automations and at operations staff who want a live feed of Workspace activity. After this guide you will know how to install the skill, how to ask an agent for it in plain language, and what to check before the agent runs anything.

Google Workspace Event Subscribergoogleworkspace/cli · Apache-2.0 Download the skill

Quick start

1Download and unzip. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
2Check prerequisites. Confirm the gws tool is installed, authentication is configured through gws, and you have a Google Cloud project ID with Pub/Sub.
3Ask the agent in plain language. Describe the Workspace resource, event type and project you want to watch.
4Review the confirmation. The agent should ask before running the write command. Check the target, event types and project.
5Choose one-off or continuous. Use --once for a single pull, or leave the listener running and stop it with Ctrl-C.
6Clean up when finished. Add --cleanup if you do not want Pub/Sub resources to persist after the session.

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 skill is installed and the agent sees a matching request, it reads those instructions and carries out the task with the tools available to it.

This skill covers the gws events +subscribe command from the googleworkspace/cli project. Events are delivered through Google Cloud Pub/Sub and printed as a stream of JSON lines (NDJSON), or saved as one JSON file per event.

Subscribes to Workspace events, for example new chat messages in a Google Chat space.
Streams events to the terminal as NDJSON, or writes each event to its own JSON file in a directory.
Asks the user for confirmation before running the command, because it creates resources.

Download the ZIP for this skill from this page and unzip it. Then place the resulting folder in one of two locations, depending on how you want it used:

For a personal install across projects, put it in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/
Project only: .claude/skills/ inside your project folder
Claude apps: Settings → Capabilities → Skills, then upload

Set up the prerequisites

The skill depends on three things. Without them the command will fail, so check them first.

The skill also refers to a shared skill, gws-shared, which explains authentication, global flags and security rules. If it is missing, the source says to run gws generate-skills to create it.

The gws command-line tool from googleworkspace/cli.
Google Workspace authentication configured through gws (see the gws-shared skill).
A Google Cloud project ID with Pub/Sub, used for event delivery.
Workspace access to the resource you want to watch.

Trigger the skill with natural requests

You do not need to type the command yourself. Describe what you want in plain language and name the Workspace resource and the project if you have them. The agent maps your request to the flags it needs.

Good requests name the resource, the event type and the project, and say whether you want a one-off pull or a continuous stream.

Subscribe to new messages in my Google Chat space SPACE and stream them in project my-project.
Pull one batch of events from the existing subscription projects/p/subscriptions/my-sub and then stop.
Stream Chat message events to ./events as one JSON file per event, and delete the Pub/Sub resources when you stop.

Command reference and examples

The main flags are --target (a Workspace resource URI such as //chat.googleapis.com/spaces/SPACE_ID), --event-types (comma-separated CloudEvents types), and --project (the GCP project ID for Pub/Sub resources). Use --subscription to reuse an existing Pub/Sub subscription and skip setup.

Other useful flags: --once pulls once and exits, --cleanup deletes created Pub/Sub resources on exit, --output-dir writes each event to a separate JSON file, --max-messages sets the batch size (default 10), --poll-interval sets seconds between pulls (default 5), and --no-ack stops automatic acknowledgement.

gws events +subscribe --target '//chat.googleapis.com/spaces/SPACE' --event-types 'google.workspace.chat.message.v1.created' --project my-project
gws events +subscribe --subscription projects/p/subscriptions/my-sub --once
gws events +subscribe ... --cleanup --output-dir ./events

Safety: scripts, network and confirmation

This skill runs scripts and uses the network. The command connects to Google Workspace and Google Cloud Pub/Sub and creates resources unless you use an existing subscription. The skill is marked as a write command, so the agent should confirm with you before it executes anything.

Without --cleanup, Pub/Sub resources persist so you can reconnect later. The listener keeps polling until you stop it. Press Ctrl-C to stop gracefully. Review the target, event types and project before you approve the run.

Confirm the target, event types and project before approving.
Use --cleanup if you do not want resources left behind.
Use --once for a single pull instead of a long-running listener.
Stop a running listener with Ctrl-C.

What people use it for

A developer triggers an automation whenever a new message is posted in a Google Chat space.
An operations team streams Workspace events to a folder of JSON files for later review.
A data team pulls one batch of events from an existing subscription to test a pipeline.
Someone reconnects to a persistent subscription after an earlier session ended.

Frequently asked questions

How do I install the gws-events-subscribe skill?

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

What do I need before the skill works?

You need the gws command-line tool from googleworkspace/cli, Google Workspace authentication configured through gws, and a Google Cloud project ID with Pub/Sub for event delivery. The gws-shared skill explains authentication.

Is the gws-events-subscribe skill free?

The skill is licensed under Apache-2.0. This page does not list prices, so check the licence terms in the source repository for details on use.

Why does the agent ask me to confirm before running it?

The skill is marked as a write command because it creates Pub/Sub resources unless you use an existing subscription. Confirming lets you check the target, event types and project first.

Why are Pub/Sub resources still there after I stop?

Without the --cleanup flag, created Pub/Sub resources persist so you can reconnect later. Add --cleanup if you want them deleted when the command exits.

How does this compare to other ways of watching Workspace events?

The source only describes this skill as a way for an agent to run gws events +subscribe and stream NDJSON or per-event JSON files. It does not compare it with other tools, so evaluate alternatives against your own needs.

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

This skill suits developers and operations staff who already have a Google Cloud project, Workspace access and the gws tool set up, and who want an agent to start and manage an event listener. Skip it if you do not have that setup, or if you do not want a persistent listener running until you stop it.

Download the skill