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

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

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for one kind of task. This skill covers one task: reading values from a Google Sheets spreadsheet. When you ask the agent for data from a specific sheet or cell range, it runs a read-only gws command and works with the returned values.

The skill does not change the spreadsheet. Writing, editing and formatting are handled by a different skill, gws-sheets.

What you need before installing

The skill cannot work without the gws command-line tool (Google Workspace CLI) installed. Your Google account must also be authenticated for gws. The source points to the shared gws-shared skill for auth setup, global flags and security rules. If that shared skill is missing, the source says to run gws generate-skills to create it.

You also need the spreadsheet ID and the range you want to read. You supply these in your request.

• gws command-line tool (Google Workspace CLI)
• Google account authentication configured for gws (see the gws-shared skill)
• Spreadsheet ID and range supplied by you

Install the gws-sheets-read skill

Download the ZIP from this page and unzip it. The skill ships as a single file, SKILL.md. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

How to trigger the skill with natural requests

You do not need to name the skill or type a command. Ask for spreadsheet data in plain language and include the spreadsheet ID and the range. The agent uses the skill when your request is about reading values from a sheet.

Give a specific sheet or cell range. Requests like 'Sheet1 rows 1 to 10' are clearer than 'look at my data'. The skill's own examples use a range such as Sheet1!A1:D10 or a whole sheet name such as Sheet1.

• Read cells A1 to D10 from spreadsheet ID 1AbC... on Sheet1 and total the Amount column.
• Pull the values from Sheet1 in spreadsheet 1AbC... and tell me which rows have a status of Late.
• Get the data in Sales!A1:F50 from this spreadsheet and summarise the monthly totals.

Run the underlying command yourself

The skill runs the same command you can run by hand. It takes a spreadsheet ID and a range. Quote the range if it contains spaces or special characters. Passing only a sheet name reads that sheet.

The source lists these flags: --spreadsheet (required, the spreadsheet ID) and --range (required, for example 'Sheet1!A1:B2').

• --spreadsheet: required, spreadsheet ID
• --range: required, range to read, e.g. Sheet1!A1:B2

Safety notes: scripts and network access

This skill runs scripts and uses the network. It calls Google Sheets through the gws tool, using your authenticated Google credentials. Only install it if you are comfortable with the agent reading that spreadsheet.

Do not use it on sensitive spreadsheets you do not want an agent to access. The skill is read-only, so it will not modify the sheet, but reading still exposes the values to the agent's session.

• Runs scripts: yes
• Uses network: yes
• Read-only: the skill never modifies the spreadsheet
• Credentials: reads go through your gws authentication

Tips for better results

For advanced options that the +read command does not offer, the source suggests using the raw values.get API instead. Check the gws-shared and gws-sheets skills for global flags and the full set of spreadsheet commands.

• Always include the spreadsheet ID and a specific range.
• If you see an authentication error, confirm gws is installed and authenticated (see gws-shared).
• Use gws sheets +read --help to see the command's help text.