How to use the Google Workspace gws CLI agent skill

What the google-workspace skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a certain kind of task. This skill covers Google Workspace. When it is installed, the agent knows to use the gws command-line tool for requests that name a Google app, instead of trying to write raw API calls by hand.

gws is a community CLI, not an official Google product. It wraps the Workspace REST APIs and covers Drive, Docs, Sheets, Gmail, Calendar, Chat, Tasks, Slides, Keep, Forms, Apps Script and Meet. The skill does not include any Google credentials, so you must set those up yourself.

• Read and write Drive, Docs, Sheets, Gmail, Calendar, Chat, Tasks and Slides
• Check for an existing access token before starting a login
• Help set up an OAuth client or service account if none exists
• Log in with read-only permissions first

How do you install the google-workspace skill?

Download the ZIP file for the skill from this page. Unzip it so that the skill folder, which contains SKILL.md, sits in one of these locations: ~/.claude/skills/ for your personal use, or .claude/skills/ inside a project folder if you want the skill limited to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

The gws CLI itself must also be installed. The skill depends on the npm package @googleworkspace/cli, so you need Node.js and npm first.

• Node.js and npm are required to install gws
• Install the CLI with: npm install -g @googleworkspace/cli
• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project

How do you set up Google authentication for gws?

Authentication is the step most people get stuck on. The skill checks for credentials in a fixed order, and you should follow the same order. If a token from the web UI's Connect Workspace feature is already present, the agent can use it directly. Otherwise, you configure an OAuth client or a service account.

To create an OAuth client by hand, choose the Desktop app client type, not Web application. The gws login listens on a local loopback port, and a Web application client rejects that with a redirect_uri_mismatch error. For a corporate Workspace organisation, you can set the consent screen audience to Internal.

For unattended automation, you can use a service account instead. Set GOOGLE_APPLICATION_CREDENTIALS to the path of your key file, and calls authenticate with that key without a login step.

• Option 1: place a client_secret.json file in the gws config directory
• Option 2: set GOOGLE_WORKSPACE_CLI_CLIENT_ID and GOOGLE_WORKSPACE_CLI_CLIENT_SECRET
• Option 3: set GOOGLE_APPLICATION_CREDENTIALS to a service account key file
• Create the OAuth client as a Desktop app; a Web application client causes a redirect error

How do you log in with read-only access first?

With an OAuth client in place, run the login with read-only scopes. This is the least-privilege starting point, and the skill recommends it. Add write scopes only when a task actually needs them, by running the login again with the scopes you need. Google's incremental consent adds the new permission to the ones already granted.

The login opens a browser on your machine and waits for a local redirect, so it needs a browser. You can check the current login state at any time with gws auth status. If you see a 403 or scope error when a request runs, the token is valid but does not include the permission that request needs.

• Start with --readonly for least privilege
• Add write scopes later, only for the surface you need
• Use -s to limit the scope picker to chosen services, for example drive, gmail and sheets
• gws auth login is browser-based and has no paste-a-code option

How do you trigger the skill with natural requests?

You do not need to name the skill. The skill applies to any request that names a Google Workspace surface. Ask in ordinary language and say which app and what you want done. The more specific you are about the file, folder, label, or calendar, the fewer back-and-forth questions the agent needs to ask.

Requests that work well include reading a Drive file, listing a folder, sharing a document, creating a Doc from a description, updating a sheet, appending a row, drafting a Gmail reply, checking a calendar, scheduling a meeting, and posting to a Chat space.

• Read this Drive file and summarise it
• List my Drive folder called Client Notes
• Append a row with today's figures to the budget sheet
• Draft a Gmail reply to the last message from Sam, but do not send it
• What is on my calendar on Thursday?
• Schedule a 30 minute meeting with the design team next week
• Post this summary to the project Chat space

What are the safety notes for this skill?

The skill runs scripts and uses the network, because gws calls Google's APIs on your behalf. Once permissions are granted, the agent can read and change your email and files. Only grant access to an account you are comfortable letting an agent use, and prefer read-only scopes wherever possible.

For shared or automated setups, use a service account that a person has reviewed, and avoid unattended write access. A bad instruction could otherwise change or send data with no one checking it. The skill also tells the agent not to use curl against the raw Workspace APIs, because gws already handles those calls.

• Grant read-only scopes first and add write access only when needed
• Do not use unattended automation without a reviewed service account
• Only use this in environments where you can install the npm package
• Keep credentials out of shared folders; the skill does not supply them

What tips help the skill work reliably?

Confirm that each Google API you need is enabled for the account or project you use. If a call fails with a quota-project 403 error, check that the project_id in your client_secret.json is a project the signed-in account is allowed to use.

If you run the agent in a sandbox, set the config directory and keyring backend on every command, because each shell call starts fresh. Keep the config directory somewhere durable so the login survives upgrades.

• Name the file, sheet, or calendar exactly to avoid extra questions
• Keep the config directory persistent so the login is not lost
• Set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file when there is no OS keyring
• Use gws auth status to check login state, but confirm with a real read when a token came from the environment