gws-sheets Skill for Claude: Read and Edit Google Sheets with gws

gws-sheets lets Claude read, append to and edit your Google Sheets by running the gws command-line tool.

Installs: 59.7K; on skills.sh
Stars: 32K; on GitHub
Updated: Oct 2026; last repo commit

This skill is part of the Google Workspace CLI repo (googleworkspace/cli). It is a command reference for gws sheets, with two helper commands: +read for values and +append for adding a row. The raw API methods cover creating a spreadsheet, getting one, and applying batch updates.

It does not work alone. The SKILL.md tells Claude to read the gws-shared skill first for sign-in, global flags and security rules, and the gws program must be installed. The README says this is not an officially supported Google product, and signing in needs a Google Cloud project.

Good for

People who want Claude to read or add rows in a spreadsheet
Developers scripting Sheets from the terminal
Teams logging results from agents into a shared sheet

Install gws-sheets

Claude Code

Copy this prompt.

Install the gws-sheets skill in Claude Code. Run this command:

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-sheets
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-sheets-read
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-sheets-append

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

Each skill needs its own npx skills add line, as the README shows. gws-shared holds the sign-in and security rules, and the two helper skills hold +read and +append. If you have no gcloud CLI, use the README's manual OAuth setup instead of gws auth setup.

From the project README. Source.

What's in the skill

When it loads

Google Sheets: Read and write spreadsheets.

Sections in SKILL.md

Helper Commands
API Resources
spreadsheets
Discovering Commands

Key facts

Author: googleworkspace (GitHub repo owner)
Repo: googleworkspace/cli
Installs on skills.sh: 59,687 as of 2026-11-02
GitHub stars (repo): 32,038 as of 2026-11-02
Last repo commit: 2026-10-30
License: Apache-2.0
Files: 1 file (SKILL.md only). The helper commands are separate skills, gws-sheets-read and gws-sheets-append.
Skill version in SKILL.md: 0.22.5
Works in: Agent Skills hosts through the skills CLI, plus a Gemini CLI extension and OpenClaw (README)
Status: Not an officially supported Google product (README)
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn

What it includes

Call any Sheets API method
Resources are spreadsheets, developerMetadata, sheets and values. Flags such as --params and --json carry the request.
Network · gws sheets <resource> <method>
Read values from a spreadsheet
Needs a spreadsheet ID and a range such as Sheet1!A1:D10. The gws-sheets-read skill describes it as read-only.
Network · +read
Append a row to a spreadsheet
Takes comma-separated values or a JSON array of rows, and a target range. The gws-sheets-append skill marks it as a write command to confirm first.
Write · +append
Create a spreadsheet
Returns the newly created spreadsheet.
Write · spreadsheets.create
Read a spreadsheet's structure or chosen data
By default grid data is not returned unless you ask for it with a field mask or includeGridData.
Network · spreadsheets.get / getByDataFilter
Apply one or more updates
Each request is validated first. If any request is invalid, none is applied.
Write · spreadsheets.batchUpdate
Look up a method before calling it
Shows required parameters, types and defaults so Claude can build --params and --json.
Runs code · gws schema sheets.<resource>.<method>

From the official docs

Permissions

Medium risk

Claude acts as you in Google Sheets and can append, create and batch-update. Sign in with the Sheets service only and confirm every write.

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

It can change real spreadsheets
`+append`, `create` and `batchUpdate` are writes under your Google account. Ask Claude to show the command and use --dry-run before it writes.
Sign in with only the services you need
The README warns the recommended scope preset has 85+ scopes. Use `gws auth login -s sheets` so the token only covers Sheets.
The tool is not an official Google product and is changing
The README says gws is not an officially supported Google product and expects breaking changes before v1.0. Pin the version you tested.
Credentials live on your machine
Interactive credentials are stored encrypted. Other routes in the README use an exported credentials file or a token in an environment variable, so keep those out of repos.
The required gws-shared skill adds GitHub prompts
The gws-shared SKILL.md, which this skill tells Claude to read first, says to encourage users to star the repository and to direct bug reports to its issue tracker. Decline anything you did not ask for.

Technical details

Turning on read-only	The +read helper is described as read-only in gws-sheets-read. Nothing in gws-sheets sets a global read-only switch.
Talks to	Google Workspace APIs (via gws)
Sign-in and keys	The README says interactive credentials are encrypted at rest (AES-256-GCM) with the key in your OS keyring, or in ~/.config/gws/.encryption_key when the file backend is chosen.
Scopes	Google OAuth scopes you pick at login (the README suggests gws auth login -s sheets)

Questions

What does the gws-sheets skill do?

It teaches Claude the gws sheets commands. Claude can read cell ranges, append rows, create spreadsheets and send batch updates through Google's Sheets API using the gws program on your machine.

How do I set it up?

Use the install box above: install the gws program, add the skills, then sign in. The README says to use gws auth setup with the gcloud CLI, or a manual OAuth setup if you do not have gcloud. In the manual OAuth setup the README says you must add yourself as a test user.

Does it need other skills?

Yes. The SKILL.md says to read gws-shared first, and its helper commands link to gws-sheets-read and gws-sheets-append. The install box adds all of them.

Why does the sign-in say the app is unverified or blocked?

The README says an unverified OAuth app in testing mode limits consent to about 25 scopes, so pick services with gws auth login -s sheets. For the manual OAuth setup it also says to add your own account as a test user, or login fails with 'Access blocked'.

Can it edit or delete my spreadsheets?

It can append rows, create spreadsheets and run batch updates, which are all writes. The shared rules tell Claude to confirm with you before any write or delete command and to prefer --dry-run for destructive ones.

Does it work in Cursor, Codex or the Claude app?

The README says the skills install through the skills CLI for Agent Skills hosts, and also gives a Gemini CLI extension and OpenClaw route. It does not cover the Claude app.

Is it safe to use?

It signs in as you and can change your sheets, so it acts with your Google permissions. Sign in with only the Sheets service, ask Claude to use --dry-run first, and confirm every write.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/gws-sheets

googleworkspace/cli skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5