Guide · Agent skill
How to use the gws CLI Shared Reference agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gws-shared skill is a reference file that teaches an AI agent how to use the gws command-line tool for Google Workspace services such as Drive and Sheets. It covers logging in, the common command syntax, global flags for output format and dry runs, and safety habits like asking before write or delete actions. After following this guide you will be able to install the skill, ask your agent for Google Workspace tasks in plain language, and know what the agent needs from you before it runs anything.
gws CLI Shared Referencegoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install the gws binary. Put the gws binary on your PATH, following the install options in the project README.
- 2Add the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Log in. Run gws auth login for browser OAuth, or set GOOGLE_APPLICATION_CREDENTIALS to a service account key file.
- 4Ask in plain language. Describe the Google Workspace task you want, and mention gws so the agent uses the right tool.
- 5Review the plan. Check the command the agent proposes, especially flags like --dry-run and any write or delete action.
- 6Confirm writes deliberately. Approve write or delete commands only after you have read them, and test on non-critical data first.
What does the gws-shared skill make the agent do?
An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for a specific job. This skill is the shared reference for the gws CLI from the googleworkspace/cli project. It does not run anything by itself. It tells the agent how to log in, how to shape a gws command, which global flags exist, and which shell quoting problems to avoid.
Once the skill is loaded, the agent knows these conventions, so it can run gws commands for you more reliably instead of guessing the syntax.
- Explains the command pattern: gws <service> <resource> [sub-resource] <method> [flags]
- Lists global flags: --format (json, table, yaml, csv), --dry-run and --sanitize
- Lists method flags such as --params, --json, --page-all, --page-limit and --page-delay
- Sets security rules: never print secrets, confirm before write or delete commands, prefer --dry-run for destructive operations
- Covers zsh and JSON quoting tips for sheet ranges and arguments
Install the gws binary and the skill
The skill needs the gws binary on your PATH. The skill file says to see the project README for install options, so follow that first. Then add the skill itself. Download the ZIP from this page and unzip it into one of these locations:
For a personal setup, unzip into ~/.claude/skills/. For a single project, unzip into that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Per project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills (upload)
Log in to Google Workspace
The skill documents two ways to authenticate. For interactive use, run the browser-based OAuth login. This requires a Google account with the right permissions for the services you want to use.
For automated or server use, you can use a service account. Point the GOOGLE_APPLICATION_CREDENTIALS environment variable at your key file. Keep that key file private.
# Browser-based OAuth (interactive)
gws auth login
# Service Account
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.jsonUse the global flags and command syntax
Every gws command follows the same shape: service, resource, optional sub-resource, method, then flags. Global flags control how output looks and whether the call is only validated. Method flags control the request itself.
Use --dry-run to validate a command locally without calling the API. The skill recommends this for destructive operations. Use --sanitize only if you have Google Cloud Model Armor set up, since it screens responses through that service.
- --format json (default), table, yaml or csv
- --dry-run: validate locally without calling the API
- --params: URL or query parameters as JSON
- --json: request body as JSON
- --page-all: auto-paginate, output as NDJSON
- --page-limit: max pages with --page-all (default 10)
- --page-delay: delay between pages in milliseconds (default 100)
- -o, --output: save binary responses to a file
- --upload: upload file content as multipart
gws <service> <resource> [sub-resource] <method> [flags]Avoid zsh and JSON quoting problems
If you use zsh, sheet ranges such as Sheet1!A1 contain a ! that zsh treats as history expansion. Wrap the range in double quotes rather than single quotes. For --params and --json values that contain double quotes, wrap the whole value in single quotes so the shell leaves the inner quotes alone.
- Sheet ranges with ! in zsh: use double quotes
- JSON arguments with double quotes: use single quotes around the value
# WRONG (zsh will mangle the !)
gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'
# CORRECT
gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"
# JSON with double quotes
gws drive files list --params '{"pageSize": 5}'Trigger the skill with natural requests
You do not need to type gws commands yourself. Ask the agent in plain language about the Google Workspace task you want done, and mention gws or Google Workspace so the agent knows which tool to use. The agent should show you the command it plans to run, and for any write or delete it should ask you to confirm first. Read the plan before you approve it.
- Example: "Use gws to list my five most recent Drive files."
- Example: "Read cells A1 to D10 from the Sheet1 tab of this spreadsheet with gws."
- Example: "Dry-run a gws command that would update this sheet, and show me the command before running it."
Safety notes: scripts and network access
This skill runs scripts and uses the network, because the gws tool calls Google APIs. The skill's security rules say the agent must never print API keys or tokens, must always confirm before write or delete commands, and should prefer --dry-run for destructive operations.
The skill relies on the agent asking for confirmation. It does not enforce that step in code. Do not rely on it for unsupervised write access to real data. Review commands before they run, and use a test spreadsheet or folder while you learn.
- Runs scripts: yes
- Uses network: yes
- Confirmation is requested by the agent, not enforced by the tool
- Feedback and bug reports go to the project's GitHub issues, after searching for an existing one
What people use it for
- List recent Google Drive files with a page size limit using --params
- Read a range of cells from a Google Sheet with the correct zsh quoting
- Validate a write command with --dry-run before anything changes
- Export command output as a table, CSV or YAML with --format
- Page through a large list of results with --page-all and --page-limit
Frequently asked questions
How do I install the gws-shared skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings → Capabilities → Skills. The gws binary must also be on your PATH, following the project README.
What do I need before the skill is useful?
You need the gws command-line binary on your PATH and a way to authenticate. That is either a Google account for browser OAuth login through gws auth login, or a service account key file referenced by GOOGLE_APPLICATION_CREDENTIALS. Model Armor is optional and only needed for the --sanitize flag.
Is the gws-shared skill free?
The skill is licensed under Apache-2.0, as listed on this page. The source does not describe pricing for Google Workspace or Google Cloud services, so check those separately for your account.
Why does my sheet range fail in zsh?
zsh treats the ! in ranges like Sheet1!A1 as history expansion. Wrap the range in double quotes instead of single quotes. The skill's shell tips show this exact fix.
Does the skill run commands on its own?
No. The skill only documents commands and conventions. The agent runs gws commands through the installed binary, and the skill relies on the agent asking you to confirm write or delete actions. That confirmation is not enforced by the tool.
What is the difference between --params and --json?
According to the skill, --params takes URL or query parameters as JSON, while --json takes the request body as JSON. Wrap either value in single quotes when it contains double quotes.
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 teams who already use or want to automate Google Workspace from the terminal and want an agent to follow consistent gws conventions. It is not a good fit if you lack the gws binary or the right Google permissions, or if you want an agent to make unsupervised changes to real data, since the confirmation step depends on the agent.
Download the skill