google-sheets

Q: How do I install google-sheets?

Run npx skills add https://github.com/odyssey4me/agent-skills --skill google-sheets in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/google-sheets/ (personal) or .claude/skills/google-sheets/ (project).

by odyssey4meData & Databases

Read, write, and format Google Sheets spreadsheets. Manage cell values, ranges, formulas, pivot tables, and charts. Use when asked to update a gsheet, edit a Google spreadsheet, add formulas, or work with spreadsheet data.

Installs: 113
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/odyssey4me/agent-skills --skill google-sheets

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads google-sheets automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Google Sheets

Interact with Google Sheets for spreadsheet management, data manipulation, and formula operations.

Installation

Dependencies: pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Setup Verification

After installation, verify the skill is properly configured:

$SKILL_DIR/scripts/google-sheets.py check

This will check:

Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
Authentication configuration
Connectivity to Google Sheets API

If anything is missing, the check command will provide setup instructions.

Authentication

Google Sheets uses OAuth 2.0 for authentication. For complete setup instructions, see:

GCP Project Setup Guide - Create project, enable Sheets API
Google OAuth Setup Guide - Configure credentials

Quick Start

Create ~/.config/agent-skills/google.yaml:

oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret

Run $SKILL_DIR/scripts/google-sheets.py check to trigger OAuth flow and verify setup.

On scope or authentication errors, see the OAuth troubleshooting guide.

Commands

See permissions.md for read/write classification of each command.

check

Verify configuration and connectivity.

$SKILL_DIR/scripts/google-sheets.py check

This validates:

Python dependencies are installed
Authentication is configured
Can connect to Google Sheets API
Creates a test spreadsheet to verify write access

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

$SKILL_DIR/scripts/google-sheets.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Credentials are saved to ~/.config/agent-skills/google-sheets.yaml.

Options:

--client-id - OAuth 2.0 client ID (required)
--client-secret - OAuth 2.0 client secret (required)

auth reset

Clear stored OAuth token. The next command that needs authentication will trigger re-authentication automatically.

$SKILL_DIR/scripts/google-sheets.py auth reset

Use this when you encounter scope or authentication errors.

auth status

Show current OAuth token information without making API calls.

$SKILL_DIR/scripts/google-sheets.py auth status

Displays: whether a token is stored, granted scopes, refresh token presence, token expiry, and client ID.

spreadsheets create

Create a new Google Sheets spreadsheet.

$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "My Spreadsheet"

Options:

--title - Spreadsheet title (required)
--sheets - Comma-separated sheet names (optional)

Example:

# Create with default Sheet1
$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "Sales Data"

# Create with custom sheets
$SKILL_DIR/scripts/google-sheets.py spreadsheets create \
  --title "Q1 Report" \
  --sheets "Summary,January,February,March"

# Output:
# ✓ Spreadsheet created successfully
# Title: Q1 Report
# Spreadsheet ID: 1abc...xyz
# Sheets: 4 (Summary, January, February, March)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit

spreadsheets get

Get spreadsheet metadata and structure.

$SKILL_DIR/scripts/google-sheets.py spreadsheets get SPREADSHEET_ID

Arguments:

spreadsheet_id - The Google Sheets spreadsheet ID

Example:

$SKILL_DIR/scripts/google-sheets.py spreadsheets get 1abc...xyz

# Output:
# Title: Sales Data
# Spreadsheet ID: 1abc...xyz
# Sheets: 2 (Sheet1, Summary)
# URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit

values read

Read cell values from a range.

$SKILL_DIR/scripts/google-sheets.py values read SPREADSHEET_ID --range "Sheet1!A1:D5"

Arguments:

spreadsheet_id - The Google Sheets spreadsheet ID

Options:

--range - Range in A1 notation (required, e.g., "Sheet1!A1:D5")
--format - Value format: FORMATTED_VALUE (default), UNFORMATTED_VALUE, or FORMULA

Example:

# Read a range
$SKILL_DIR/scripts/google-sheets.py values read 1abc...xyz --range "Sheet1!A1:C3"

# Output (formatted as table):
# Name      | Age | City
# Alice     | 30  | NYC
# Bob       | 25  | LA

# Read formulas
$SKILL_DIR/scripts/google-sheets.py values read 1abc...xyz \
  --range "Sheet1!D1:D10" \
  --format FORMULA

See references/range-notation.md for A1 notation details.

values write

Write values to a range.

$SKILL_DIR/scripts/google-sheets.py values write SPREADSHEET_ID \
  --range "Sheet1!A1" \
  --values '[[\"Name\",\"Age\"],[\"Alice\",30]]'

Arguments:

spreadsheet_id - The Google Sheets spreadsheet ID

Options:

--range - Starting range in A1 notation (required)
--values - Values as JSON 2D array (required)

Example:

# Write data starting at A1
$SKILL_DIR/scripts/google-sheets.py values write 1abc...xyz \
  --range "Sheet1!A1" \
  --values '[[\"Product\",\"Price\",\"Quantity\"],[\"Widget\",9.99,100]]'

# Write a single row
$SKILL_DIR/scripts/google-sheets.py values write 1abc...xyz \
  --range "Sheet1!A5" \
  --values '[[\"Total\",999,50]]'

# Output:
# ✓ Values written successfully
#   Updated cells: 6
#   Updated range: Sheet1!A1:C2

Note: Values are entered as the user would type them. Formulas start with =.

values append

Append rows to the end of a sheet.

$SKILL_DIR/scripts/google-sheets.py values append SPREADSHEET_ID \
  --range "Sheet1" \
  --values '[[\"New\",\"Row\",\"Data\"]]'

Arguments:

spreadsheet_id - The Google Sheets spreadsheet ID

Options:

--range - Sheet name or range (required)
--values - Values as JSON 2D array (required)

Example:

# Append a single row
$SKILL_DIR/scripts/google-sheets.py values append 1abc...xyz \
  --range "Sheet1" \
  --values '[[\"Charlie\",35,\"Chicago\"]]'

# Append multiple rows
$SKILL_DIR/scripts/google-sheets.py values append 1abc...xyz \
  --range "Sheet1" \
  --values '[[\"David\",28,\"Boston\"],[\"Eve\",32,\"Seattle\"]]'

# Output:
# ✓ Values appended successfully
#   Updated cells: 3
#   Updated range: Sheet1!A4:C4

values clear

Clear values in a range.

$SKILL_DIR/scripts/google-sheets.py values clear SPREADSHEET_ID --range "Sheet1!A1:D10"

Arguments:

spreadsheet_id - The Google Sheets spreadsheet ID

Options:

--range - Range in A1 notation (required)

Example:

# Clear a range
$SKILL_DIR/scripts/google-sheets.py values clear 1abc...xyz --range "Sheet1!A1:Z100"

# Output:
# ✓ Values cleared successfully
#   Cleared range: Sheet1!A1:Z100

Warning: This only clears values, not formatting or formulas in protected cells.

sheets create

Add a new sheet to a spreadsheet.

$SKILL_DIR/scripts/google-sheets.py sheets create SPREADSHEET_ID --title "New Sheet"

Arguments:

spreadsheet_id - The Google Sheets spreadsheet ID

Options:

--title - Sheet title (required)

Example:

$SKILL_DIR/scripts/google-sheets.py sheets create 1abc...xyz --title "Q2 Data"

# Output:
# ✓ Sheet created successfully
#   Title: Q2 Data
#   Sheet ID: 123456789

sheets delete

Delete a sheet from a spreadsheet.

$SKILL_DIR/scripts/google-sheets.py sheets delete SPREADSHEET_ID --sheet-id 123456789

Arguments:

spreadsheet_id - The Google Sheets spreadsheet ID

Options:

--sheet-id - Sheet ID (required, not the title!)

Example:

# Get sheet IDs first
$SKILL_DIR/scripts/google-sheets.py spreadsheets get 1abc...xyz

# Delete a sheet
$SKILL_DIR/scripts/google-sheets.py sheets delete 1abc...xyz --sheet-id 123456789

# Output:
# ✓ Sheet deleted successfully

Warning: Cannot delete the last remaining sheet in a spreadsheet.

Examples

Create and populate a spreadsheet

# Create spreadsheet
$SKILL_DIR/scripts/google-sheets.py spreadsheets create --title "Employee Data"

# Write headers (use the spreadsheet ID from the output above)
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Name","Department","Salary","Start Date"]]'

# Append employee records
$SKILL_DIR/scripts/google-sheets.py values append $SS_ID \
  --range "Sheet1" \
  --values '[["Alice","Engineering",120000,"2023-01-15"],["Bob","Sales",95000,"2023-03-01"]]'

# Add a summary sheet
$SKILL_DIR/scripts/google-sheets.py sheets create $SS_ID --title "Summary"

# Read the data
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID --range "Sheet1!A1:D10"

Work with formulas

# Write data with formulas
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Item","Price","Qty","Total"],["Widget",10,5,"=B2*C2"],["Gadget",20,3,"=B3*C3"]]'

# Read formulas
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID \
  --range "Sheet1!D2:D3" \
  --format FORMULA

# Read calculated values
$SKILL_DIR/scripts/google-sheets.py values read $SS_ID \
  --range "Sheet1!D2:D3" \
  --format FORMATTED_VALUE

Batch operations

#!/bin/bash
SS_ID="your-spreadsheet-id"

# Clear old data
$SKILL_DIR/scripts/google-sheets.py values clear $SS_ID --range "Sheet1!A1:Z1000"

# Write new data in batches
$SKILL_DIR/scripts/google-sheets.py values write $SS_ID \
  --range "Sheet1!A1" \
  --values '[["Date","Revenue","Expenses","Profit"]]'

for month in Jan Feb Mar; do
  $SKILL_DIR/scripts/google-sheets.py values append $SS_ID \
    --range "Sheet1" \
    --values "[[\"\$month\",10000,7000,\"=B${ROW}-C${ROW}\"]]"
done

Error Handling

Authentication and scope errors are not retryable. If a command fails with an authentication error, insufficient scope error, or permission denied error (exit code 1), stop and inform the user. Do not retry or attempt to fix the issue autonomously — these errors require user interaction (browser-based OAuth consent). Point the user to the OAuth troubleshooting guide.

Retryable errors: Rate limiting (HTTP 429) and temporary server errors (HTTP 5xx) may succeed on retry after a brief wait. All other errors should be reported to the user.

Model Guidance

This skill makes API calls requiring structured input/output. A standard-capability model is recommended.

Troubleshooting

Cannot find spreadsheet

Make sure you're using the correct spreadsheet ID from the URL:

URL: https://docs.google.com/spreadsheets/d/1abc...xyz/edit
Spreadsheet ID: 1abc...xyz

Invalid range errors

Use proper A1 notation: Sheet1!A1:D5
Sheet names with spaces need quotes: 'My Sheet'!A1:B2
See references/range-notation.md for details

JSON parsing errors for --values

Ensure proper JSON escaping:

# Correct
--values '[["Hello","World"]]'
--values "[[\"Name\",\"Age\"]]"

# Incorrect
--values [[Hello,World]]  # Missing quotes

Sheet ID vs Sheet Title

Commands use different identifiers:

sheets create - Uses title (string)
sheets delete - Uses sheet ID (number)
Use spreadsheets get to find sheet IDs

API Reference

For advanced usage, see:

Google Sheets API Documentation
Reading and writing cell values
A1 notation reference
Formula examples

FAQ

What does the google-sheets skill do?

How do I install google-sheets?

Run npx skills add https://github.com/odyssey4me/agent-skills --skill google-sheets in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/google-sheets/ (personal) or .claude/skills/google-sheets/ (project).

Which AI agents can use google-sheets?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is google-sheets safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains google-sheets?

It is published by odyssey4me in odyssey4me/agent-skills. It has 113 recorded installs.

More from odyssey4me/agent-skills

View all →

google-calendar

odyssey4me/agent-skills

Create, update, and organize Google Calendar events and schedules. Check availability, book time, and manage calendars. Use when asked to schedule a meeting, set up an appointment, book a call, check gcal, or manage calendar events.

Productivity & Automation1.2K installs

google

odyssey4me/agent-skills

Google Workspace CLI for Gmail, Calendar, Drive, Docs, Sheets, and Slides using gogcli. Use when asked to search email, schedule meetings, manage files, edit documents, update spreadsheets, or create presentations.

Productivity & Automation841 installs

gitlab

odyssey4me/agent-skills

Open the skill to read its SKILL.md instructions.

AI & Agents301 installs

google-drive

odyssey4me/agent-skills

Open the skill to read its SKILL.md instructions.

AI & Agents299 installs

gmail

odyssey4me/agent-skills

Send, search, and organize Gmail messages, drafts, and labels. Read full threads and get shareable Google Groups permalinks. Use when asked to compose an email, reply to mail, forward a message, search inbox, manage attachments, organize Gmail, read a thread, or find a Google Groups discussion link.

Productivity & Automation292 installs

google-docs

odyssey4me/agent-skills

Open the skill to read its SKILL.md instructions.

Docs & Writing262 installs

Popular data & databases skills

View category →

supabase-postgres-best-practices

supabase/agent-skills

Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.

OfficialData & Databases462.2K installs

prisma-client-api

prisma/skills

Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".

OfficialData & Databases393.5K installs

prisma-database-setup

prisma/skills

Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.

OfficialData & Databases392.3K installs

prisma-cli

prisma/skills

Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.

OfficialData & Databases390.8K installs

prisma-postgres

prisma/skills

Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.

OfficialData & Databases384.4K installs

prisma-driver-adapter-implementation

prisma/skills

Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.

OfficialData & Databases378.9K installs

google-sheets

Install

Install

Describe the task

Review the result

SKILL.md

Google Sheets

Installation

Setup Verification

Authentication

Quick Start

Commands

check

auth setup

auth reset

auth status

spreadsheets create

spreadsheets get

values read

values write

values append

values clear

sheets create

sheets delete

Examples

Create and populate a spreadsheet

Work with formulas

Batch operations

Error Handling

Model Guidance

Troubleshooting

Cannot find spreadsheet

Invalid range errors

JSON parsing errors for --values

Sheet ID vs Sheet Title

API Reference

FAQ

More from odyssey4me/agent-skills

Popular data & databases skills