Guide · Agent skill
How to use the Google Workspace Events agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gws-events skill is a set of instructions that teaches an AI agent how to use the gws command-line tool to work with Google Workspace Events, the notifications sent when activity happens in Google Workspace apps. This guide is for developers, admins and engineers who want an agent to list, create, inspect, update, reactivate or delete event subscriptions, or to stream incoming events. By the end you will know what the skill does, how to install it, how to ask for things in plain language, and what to check before letting it change a live account.
Google Workspace Eventsgoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install gws. Install the gws command-line tool and confirm that gws events --help runs.
- 2Configure authentication. Set up Google Workspace authentication through gws, following the gws-shared skill.
- 3Download the skill ZIP. Download the gws-events ZIP from this directory page.
- 4Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
- 5Ask in plain language. Make a request such as listing your subscriptions. The agent will inspect the method and run the matching gws events command.
- 6Review changes. Before any create, patch or delete runs, check the request the agent shows you.
What the gws-events skill lets an agent do
An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for a specific task. The gws-events skill covers the events part of the gws tool. Once it is installed, the agent knows how to run gws events commands on your behalf.
The skill describes two helper commands: +subscribe, which subscribes to Workspace events and streams them as NDJSON, and +renew, which renews or reactivates Workspace Events subscriptions. It also covers the subscriptions resource, with methods to create, delete, get, list, patch (update or renew) and reactivate subscriptions.
- list: list Google Workspace subscriptions
- get: get details about one subscription
- create: create a subscription
- patch: update or renew a subscription
- reactivate: reset a suspended subscription to ACTIVE
- delete: delete a subscription
- +subscribe: stream events as NDJSON
- +renew: renew or reactivate subscriptions
Install the gws-events skill
The skill is distributed as a ZIP file from the skill's page in this directory. Download the ZIP and unzip it into one of two locations. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.
If you use the Claude apps instead, you can upload the skill there. Open Settings, go to Capabilities, then choose Skills and upload the ZIP.
The skill cannot work on its own. You also need the gws command-line tool installed and authenticated. The skill refers to a shared skill called gws-shared for authentication, global flags and security rules. If that file is missing, the skill says to run gws generate-skills to create it.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you start
The skill needs the gws binary on your path and Google Workspace authentication configured through gws. The skill metadata lists gws as a required binary. Its help command is gws events --help.
The skill runs scripts and uses the network, because it calls Google Workspace APIs through gws. Make sure you are comfortable with that before you install it.
- gws command-line tool (Google Workspace CLI) installed
- Google Workspace authentication configured through gws (see gws-shared)
- Network access for the API calls
gws events --helpTrigger the skill with natural requests
You do not need to type the command yourself. Ask the agent for the result you want, and it should pick the gws events commands it needs. The skill tells the agent to inspect a method before calling it, so it can build the correct parameters.
Good requests name the resource and the action. Requests that mention a subscription name or ID give the agent more to work with.
- List the Workspace event subscriptions in my project.
- Show me the details of the subscription with this ID.
- Reactivate the subscription that was suspended and tell me what error caused it.
- Stream incoming Workspace events and show me the first ten as they arrive.
- Create a subscription for the events I describe, but show me the request before you send it.
See how the agent works out the commands
The skill tells the agent to browse resources and methods first, then check the required parameters for the method it plans to use. Its main pattern is gws events <resource> <method> [flags]. You can run the same discovery steps yourself to see what the agent will do.
The agent uses the output of gws schema to build its --params and --json flags. If a call fails, the schema output is the place to check what the method expects.
gws events --help
gws schema events.<resource>.<method>Use it safely
Create, patch and delete calls change real account settings. Read or list calls only read data. Ask the agent to show you the request before it runs any change, and review the subscription details it proposes.
Reactivate only works on a subscription that is suspended, and the skill says you must fix the error that suspended it first. The agent should reject a reactivate request for a subscription that is not suspended, so do not try to force it.
Authentication and security rules live in the gws-shared skill. Read that file before you give the agent access to a production account.
- Review every create, patch and delete request before it runs
- Fix the cause of a suspension before reactivating
- Read gws-shared for auth and security rules
What people use it for
- Listing the event subscriptions in a Workspace project to audit what is being monitored.
- Checking the state of one subscription and finding out whether it has been suspended.
- Reactivating a suspended subscription after the underlying error has been fixed.
- Streaming incoming Workspace events to the terminal to see what a new automation receives.
- Renewing or updating an existing subscription with patch.
Frequently asked questions
How do I install the gws-events skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
Does the gws-events skill work without the gws CLI?
No. The skill relies on the gws command-line tool and its authentication, and it cannot work without them. Install gws and configure authentication through gws first.
What do I need to set up before using gws-events?
You need the gws tool installed and Google Workspace authentication configured through gws. The skill points to the gws-shared skill for auth, global flags and security rules. If that is missing, run gws generate-skills.
Is the gws-events skill free?
The source does not state pricing. It is listed under the Apache-2.0 licence. Check the licence file in the googleworkspace/cli repository for the terms.
Can the agent change my live Workspace subscriptions?
Yes. Create, patch and delete calls modify real account settings, so review each request before it runs. Listing and getting subscriptions only reads data.
What is the difference between +subscribe and +renew?
+subscribe subscribes to Workspace events and streams them as NDJSON. +renew renews or reactivates Workspace Events subscriptions.
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 gws-events if you already use the gws CLI and want an agent to manage or monitor Google Workspace event subscriptions. Skip it if you do not have gws installed and authenticated, or if you want subscription changes made without your review, since create, patch and delete calls change live account settings.
Download the skill