How to use the Google Workspace CLI Admin agent skill

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

An agent skill is a folder with a SKILL.md file and supporting files that an AI agent loads when your request matches the skill's description. This skill gives the agent guidance for Google Workspace administration using the gws CLI (github.com/googleworkspace/cli, Apache-2.0 licensed).

Once installed, the agent can guide you through installing and signing in to gws, run helper scripts that check your setup, and draft or run commands to send email, search Gmail, manage Drive files and sharing, read or write Sheets, and schedule Calendar events. It also includes a local catalog of recipe templates, persona bundles and a script that audits Workspace settings.

• Gmail: send, reply, forward, search and label messages
• Drive and Sheets: list, upload, create and share files; read and append sheet data
• Calendar: create events, list upcoming events, check free/busy time
• Security: run a Workspace audit and get remediation commands

Install the skill from the ZIP

Download the ZIP for this skill from the page where you found this guide. Unzip it so that the folder containing SKILL.md sits in one of these locations:

For personal use across projects, put it in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/google-workspace-cli/
• Project: .claude/skills/google-workspace-cli/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Install the gws CLI and sign in

The skill does not replace the gws tool, so install it separately. The source lists three options. The npm route is recommended and needs Node.js 18+. Homebrew works on macOS and Linux, and Cargo builds from source. Pre-built binaries are also available on the releases page.

Sign-in needs a Google Cloud project with OAuth credentials (a client ID and secret) or a service account. Run the bundled guide to walk through creating them, then run the interactive setup and request only the scopes you need.

• Install with npm: npm install -g @googleworkspace/cli
• Check the install: gws --version
• Get OAuth setup instructions: python3 scripts/auth_setup_guide.py --guide oauth
• Run interactive setup: gws auth setup
• Log in with limited scopes: gws auth login -s drive,gmail,sheets

Check your setup with the doctor script

Ask the agent to check your installation, or run the doctor script yourself. It checks the PATH, the gws version, authentication status and service connectivity. Python 3 is needed to run the bundled scripts.

For headless or CI machines, the source describes exporting credentials from an interactive machine and pointing the CLI at the file with an environment variable. Validate authentication with the auth guide script, which tests each service endpoint.

Trigger the skill with natural requests

You do not need to type script names. Describe the task in plain language and mention Google Workspace or gws. The skill's description matches requests about Workspace admin, gws CLI setup, Gmail automation, Drive management and Calendar scheduling.

Good requests name the service, the action and the scope. For example, ask the agent to check whether gws is installed and signed in, or to draft a command that lists Drive files and formats the output as a table. Expect the agent to show commands for your review and to flag ones it has not verified.

• Set up gws on this machine and check that authentication works
• Draft a command to find Gmail messages from a client sent after 1 January 2025
• Schedule a team sync on Calendar next Tuesday; show me the command first
• Audit my Workspace security settings and list the findings

Review commands before you run them

The source is explicit that gws builds its commands at runtime from Google's API discovery documents and that the CLI is pre-v1.0. Many commands in the skill are marked (verify). Before putting a command into automation, confirm its exact surface with gws --help, gws <service> --help or gws schema <service>.<resource>.<method>.

Bulk actions deserve extra care. The source recommends --dry-run before bulk operations and --page-all to paginate. Sharing and archive commands can change real data, so review who or what they affect first.

• Check syntax: gws gmail users messages list --help or gws schema gmail.users.messages.modify
• Use --dry-run first for bulk Gmail or Drive changes
• Test on a non-critical account or a small set of items before scaling

Safety notes: scripts and network access

This skill runs scripts and uses the network. The bundled Python scripts (gws_doctor.py, auth_setup_guide.py, gws_recipe_runner.py, output_analyzer.py and workspace_audit.py) run on your machine, and the gws commands call Google's APIs using the OAuth credentials you set up. Read the scripts and the commands before running them, particularly on accounts that hold sensitive mail or organisation-wide sharing.

Credentials are sensitive. The export command writes a credentials file in plain form when used with --unmasked, so store it securely and avoid committing it to version control.

• Scripts run locally with Python 3
• Network calls go to Google services through your own OAuth client or service account
• Keep credentials.json out of shared folders and repositories