Google Workspace CLI Agent Skills
A collection of Agent Skills bundled with Google Workspace CLI that helps agents operate Gmail, Drive, Calendar, Sheets, Docs, and other Workspace services through gws, with cross-service workflows and safety rules.
Project overview
Google Workspace CLI Agent Skills is the skill collection in the googleworkspace/cli repository. It describes Gmail, Drive, Calendar, Sheets, Docs, and other APIs in SKILL.md files that agents can read, then combines services through persona and recipe workflows. The gws CLI performs the actual operations. It suits people and teams that want agents to handle routine Workspace work and are prepared to manage OAuth scopes, cloud writes, and sensitive data carefully.
Core capabilities
Workspace service Skills
gws-prefixed Skills cover Drive, Gmail, Calendar, Sheets, Docs, Slides, Chat, Admin, and other services, plus schema, batch, help, and shared safety instructions.
Persona workflows
Persona Skills organize common tasks for executive assistants, project managers, salespeople, researchers, and other roles, giving a host one role-oriented entry point into multiple Workspace operations.
Cross-service recipes
Recipe Skills combine email, file, calendar, document, and spreadsheet commands into concrete workflows. They work best as reviewable execution templates with confirmations around external writes.
Structured commands and previews
gws provides JSON output, schema inspection, automatic pagination, NDJSON streaming, and dry-run support. Agents can inspect request shapes and previews before performing writes.
Authentication and sensitive-content controls
The CLI supports interactive OAuth, credential files, service accounts, and pre-obtained access tokens. The shared Skill says not to output secrets, to confirm writes and deletes, and optionally to use Model Armor for content checks.
Installation and usage
Install gws CLI and complete minimal-scope OAuth before adding the needed Skills to the target agent host. Validate identity and output with a read-only command first, then expand to writes after reviewing scopes.
Let an AI Agent install it
Send this prompt to Codex, Claude Code, or another AI agent that can work with your local environment.
Help me install Google Workspace CLI Agent Skills from https://github.com/googleworkspace/cli. First read README.md, docs/skills.md, skills/gws-shared/SKILL.md, SECURITY.md, and LICENSE. Explain whether you will install gws CLI, the Skills, or both. Prefer the gws binary for my operating system and architecture from GitHub Releases, or use `npm install -g @googleworkspace/cli` or `brew install googleworkspace-cli` when appropriate. Install only the Skills needed for my task, such as `npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive`. Start OAuth with a minimal service set such as `gws auth login -s drive,gmail,sheets`. Never print tokens, client secrets, or credential file contents. Ask me before sending messages, sharing files, changing spreadsheets, creating events, or deleting data, and use `--dry-run` where supported. Verify only with a read-only list command.- A prebuilt gws binary, or one of Node.js 18+, Homebrew, Cargo, and Nix
- A Google Cloud project
- A Google account with access to Google Workspace
- An Agent Skills-compatible host, Gemini CLI, or OpenClaw
- Authority to approve the required OAuth scopes
npx skills add https://github.com/googleworkspace/cli- 1Install and inspect gws CLI
Download a prebuilt binary from Releases, or use `npm install -g @googleworkspace/cli` or `brew install googleworkspace-cli`. Run `gws --version` and `gws --help` to confirm PATH and version.
- 2Configure minimal OAuth access
With gcloud available, run `gws auth setup`, then use `gws auth login -s drive,gmail,sheets` to select only the services needed now. For manual setup, save the Desktop OAuth client to the configuration path documented in the README.
- 3Install only the needed Skills
Use `npx skills add` for the entire repository, or select directories such as `skills/gws-drive` and `skills/gws-gmail`. A smaller set makes it easier to review what instructions and commands the host loaded.
- 4Verify with a read-only request
Run `gws drive files list --params '{"pageSize": 5}'` and inspect the account, fields, and count returned. Do not send email, share files, or modify data during the first check.
- 5Enable writes gradually
Choose one recipe and inspect the services and objects it will access. Preview commands with `--dry-run` where supported, then confirm the request body, target, and scopes before execution.
Run `gws --version`, then use `gws auth login -s drive,gmail,sheets` to select only the required services. After login, run `gws drive files list --params '{"pageSize": 5}'` as a read-only check and confirm that the host can discover the installed gws-drive or gws-gmail Skill.
- The README recommends the prebuilt binary matching the operating system and architecture.
- gws auth setup depends on gcloud. Without gcloud, follow the README's manual Desktop OAuth client path.
- For OAuth apps in testing mode, avoid the recommended preset that contains more than 85 scopes.
- An unmasked credentials.json exported for headless use is sensitive and should have restricted permissions and stay out of version control.
Use cases
Triage daily email and follow-ups
Use Gmail Skills to query a time range and labels, summarize messages that need replies, and keep the actual send action behind user confirmation.
Prepare meeting material
Combine Calendar, Drive, Docs, and Gmail to locate events and related files and draft a pre-meeting brief. Confirm targets again before sharing documents or contacting attendees.
Update a shared spreadsheet
Read the Sheets headers and current range before preparing an explicit append or update request. The latest version adds an append range parameter for targeting a specific tab.
Inventory Drive files in bulk
Use pagination and NDJSON output to collect a file list, then classify it with jq or an agent. Separate deletion, moving, and sharing into their own approval steps.
Assessment
The collection benefits from keeping the CLI and skill instructions in one repository, so commands, authentication guidance, and workflow examples can evolve together. The 95 Skills provide broad coverage, while structured JSON, schema inspection, and dry-run support suit agent execution. Most operational cost lies in Google Cloud OAuth setup, scope control, and review of external writes. The project remains pre-v1, and its README gives inconsistent Skill counts, so a small service-specific trial is the practical starting point. This page reviews public material only and does not claim installation or functional testing.
Why it may be useful
- CLI, shared rules, service Skills, personas, and recipes are maintained together
- Structured JSON, schema inspection, pagination, and dry-run support machine use and human review
- Installation and authentication cover desktop, CI, service-account, and pre-obtained-token scenarios
- Apache-2.0 licensing, a security-reporting channel, and Release information are clear
What to know first
- Pre-v1 versions may introduce breaking changes
- Google OAuth configuration and scope management require care
- The README's 40+, 100+, and actual 95 Skill counts do not align
- Whether an agent follows confirmation and sensitive-data rules depends on the host and runtime
README
Google Workspace CLI Agent Skills
Overview
A collection of Agent Skills bundled with Google Workspace CLI that helps agents operate Gmail, Drive, Calendar, Sheets, Docs, and other Workspace services through gws, with cross-service workflows and safety rules. Google Workspace CLI and its AI Agent Skills provide a structured Workspace API command surface for people and agents.
Getting started
- Install gws CLI and complete minimal-scope OAuth before adding the needed Skills to the target agent host. Validate identity and output with a read-only command first, then expand to writes after reviewing scopes.
- gws is a Rust-based Google Workspace CLI. It reads Google Discovery Service at runtime so its command surface can follow public API changes, and it returns structured JSON by default.
- The repository groups Skills into services and helpers, role personas, and cross-service recipes. A direct count of main on 2026-09-18 found 95 SKILL.md files, comprising 44 gws, 10 persona, and 41 recipe Skills.
- Run `gws --version`, then use `gws auth login -s drive,gmail,sheets` to select only the required services. After login, run `gws drive files list --params '{"pageSize": 5}'` as a read-only check and confirm that the host can discover the installed gws-drive or gws-gmail Skill.
Configuration
npx skills add https://github.com/googleworkspace/cli