Skip to content
Get packs

Guide · Agent skill

How to use the Google Sheets Access agent skill (gws-sheets)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The gws-sheets skill is a set of instructions that teaches an AI agent how to work with Google Sheets through the gws command-line tool. It is aimed at people who already use Google Sheets and want an agent to append rows, read values, create spreadsheets or apply batch updates. After this guide you will know what the skill does, how to install it, how to ask for things in plain language, and what to check before giving an agent write access.

Google Sheets Accessgoogleworkspace/cli · Apache-2.0

Quick start

  1. 1Download the ZIP. Download the gws-sheets skill ZIP from this page.
  2. 2Install the skill. Unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Install the gws tool. Make sure the separate gws command-line tool is installed, since the skill cannot work without it.
  4. 4Set up authentication. Configure Google account access through gws using the shared auth guide, or run gws generate-skills if gws-shared SKILL.md is missing.
  5. 5Check the commands. Run gws sheets --help to confirm the tool can see the Sheets commands.
  6. 6Make a request. Ask the agent in plain language, naming the spreadsheet and the data you want to read or append.

What the gws-sheets skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an agent instructions for a specific task. This one covers Google Sheets (Sheets API v4). Once installed, the agent knows which gws sheets commands exist and how to call them.

The skill mainly provides a map of available commands. It lists two helper commands, +append (append a row to a spreadsheet) and +read (read values from a spreadsheet), and the API resources spreadsheets, values, sheets and developerMetadata. Among the spreadsheets methods it documents are batchUpdate, create, get and getByDataFilter.

Install the gws-sheets skill

The skill is distributed as a ZIP file. Download it from this page, then choose one of the two options below.

For Claude Code, unzip the file into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

  • Option A: unzip into ~/.claude/skills/ (personal, all projects)
  • Option B: unzip into .claude/skills/ inside a project (that project only)
  • Option C: upload the ZIP in the Claude apps under Settings → Capabilities → Skills

Install the gws tool and set up authentication

The skill does not reach your Google account on its own. It relies on the separate gws command-line tool (Google Workspace CLI) and its shared authentication setup. The skill's SKILL.md points to a gws-shared SKILL.md for auth, global flags and security rules. That file is not included in this package. If it is missing, the source says to run gws generate-skills to create it.

Confirm that the gws tool is available before you ask the agent to do anything with your spreadsheets.

gws sheets --help

Ask for Sheets work in plain language

You do not need to know command syntax. Describe the outcome you want, and name the spreadsheet and the sheet or data involved so the agent can find it. Because the skill documents +append and +read, requests about logging a row or pulling values are the most direct.

The agent is told to inspect each method before calling it, so it may check parameters first. You can ask it to do this explicitly if you want to see the plan.

  • Append a row with today's date, the amount and the customer name to my Expenses spreadsheet.
  • Read the values from the Leads sheet in my spreadsheet and summarise the rows marked 'new'.
  • Create a new spreadsheet called Q3 Tracker.
  • Apply these updates to the spreadsheet with ID [your ID] and tell me what changed.

How the agent checks commands before running them

The skill tells the agent to inspect a method before calling it. Browsing and inspection use these commands from the source. The output of gws schema is used to build the --params and --json flags.

If you are a developer, you can run the same commands yourself to learn the parameters before writing a script.

# Browse resources and methods gws sheets --help # Inspect a method's required params, types, and defaults gws schema sheets.<resource>.<method>

Safety notes: scripts, network and write access

This skill runs scripts and uses the network. The gws tool calls Google services through your authenticated account, so the skill can modify and create spreadsheets there. Treat it as having the same reach as your Google login through gws.

The source notes that batchUpdate validates every request first and fails entirely if any request is invalid, so nothing is applied. It does not say that changes can be undone, so keep backups of important sheets.

  • Do not connect sensitive spreadsheets unless you are comfortable with the agent writing to them.
  • Review the batchUpdate request before the agent runs it on important data.
  • Read the shared auth and security rules in gws-shared SKILL.md before you rely on the setup.

Tips for better results

Give the agent the spreadsheet ID or an exact name, and the sheet tab name when there are several tabs. Ask for a read before a write so you can confirm the layout first.

For larger data, the source notes that get returns no grid data by default. You can request grid data with a field mask in the fields URL parameter or by setting includeGridData to true.

  • Start with a read to confirm column order before asking for appends.
  • Use getByDataFilter when you only need selected subsets of a spreadsheet, as the source describes it.
  • Keep the gws command reference open with gws sheets --help while you learn.

What people use it for

  • Logging a new row, such as an expense or lead, into an existing spreadsheet.
  • Pulling values from a sheet so the agent can summarise or check them.
  • Creating a fresh spreadsheet for a project or tracker.
  • Applying a set of batch updates to an existing spreadsheet in one request.
  • Automating spreadsheet steps inside a script or workflow that already uses the gws CLI.

Frequently asked questions

Is the gws-sheets skill free?

The skill is licensed under Apache-2.0, according to the listing. The gws tool it depends on is a separate download, so check its own terms before you use it.

What do I need before installing gws-sheets?

You need a Google account, the separate gws command-line tool installed, and Google account authentication configured through gws. The skill documents commands only, so it cannot work alone.

Where do I put the skill after downloading it?

Unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

Why does the agent say the gws tool is missing?

The skill requires the gws binary. Run gws sheets --help in your terminal to check it works. If the shared auth file is missing, the source says to run gws generate-skills.

Can the agent delete or change my spreadsheets?

The skill documents methods that create spreadsheets and apply batch updates, so it can modify and create them through your account. Limit this by only connecting spreadsheets you are happy for the agent to change.

How is this different from using the Google Sheets web app or another skill?

The skill gives an agent a documented command map for Sheets through gws, rather than working in the browser. The source does not compare it with other tools, so judge the fit against your own workflow.

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

Choose gws-sheets if you already use Google Sheets and want an agent to append, read, create or batch-update spreadsheets through the gws tool. Skip it if you do not have a Google account, cannot install gws, or need the agent kept away from important spreadsheets.

Download the skill