home / skills / idanbeck / claude-skills / google-sheets-skill

google-sheets-skill skill

safe

/google-sheets-skill

This skill helps you read, write, and manage Google Sheets by automating data retrieval, updates, and sheet creation.

npx playbooks add skill idanbeck/claude-skills --skill google-sheets-skill

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.3 KB

---
name: google-sheets-skill
description: Read and write Google Sheets. Use when the user asks to read spreadsheet data, update cells, create sheets, or work with Google Sheets.
allowed-tools: Bash, Read
---

# Google Sheets Skill

Read, write, and manage Google Sheets.

## Setup

Uses same Google OAuth as gmail-skill. If you have gmail-skill configured, this will work automatically.

Otherwise:
1. Go to https://console.cloud.google.com/apis/credentials
2. Create OAuth client (Desktop app)
3. Enable Google Sheets API
4. Download JSON to `~/.claude/skills/google-sheets-skill/credentials.json`
5. Run: `python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py login`

## Commands

### List & Info

```bash
# List your spreadsheets
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py list [--limit N]

# Get spreadsheet info
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py get SPREADSHEET_ID
```

### Reading Data

```bash
# Read a range
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py read SPREADSHEET_ID "Sheet1!A1:C10"

# Read entire sheet
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py read SPREADSHEET_ID "Sheet1"
```

### Writing Data

```bash
# Write to range (overwrites)
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py write SPREADSHEET_ID "Sheet1!A1" --values '[["Header1","Header2"],["Row1","Data"]]'

# Append rows
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py append SPREADSHEET_ID "Sheet1" --values '[["New","Row"]]'

# Clear range
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py clear SPREADSHEET_ID "Sheet1!A1:C10"
```

### Sheet Management

```bash
# Create new spreadsheet
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py create --title "My Spreadsheet"

# Add sheet to existing spreadsheet
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py add-sheet SPREADSHEET_ID --title "New Tab"

# Delete sheet
python3 ~/.claude/skills/google-sheets-skill/sheets_skill.py delete-sheet SPREADSHEET_ID --sheet-id 123456
```

## Range Notation

- `Sheet1!A1:C10` - Specific range
- `Sheet1!A:C` - Entire columns A-C
- `Sheet1!1:10` - Rows 1-10
- `Sheet1` - Entire sheet
- `A1:C10` - Default sheet

## Spreadsheet ID

Found in the URL: `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`

## Output

All commands output JSON.

Overview

This skill reads, writes, and manages Google Sheets via the Google Sheets API. It supports reading ranges or whole sheets, updating or appending rows, creating and deleting sheets, and exporting results as JSON. Setup uses Google OAuth credentials for secure access.

How this skill works

The skill authenticates with Google OAuth and calls the Google Sheets API to list spreadsheets, fetch sheet metadata, read cell ranges, overwrite or append values, and perform sheet-level operations (create, add, delete). Commands accept spreadsheet IDs and A1-style ranges and return JSON-formatted responses for easy integration. Credential setup is required once; subsequent requests reuse the authenticated session.

When to use it

Import or export tabular data between apps and Google Sheets
Automate writing reports, logs, or form results into a sheet
Read specific ranges or entire sheets for analysis or downstream processing
Create templates, add or remove tabs programmatically
Append rows when collecting incremental records or events

Best practices

Store and protect OAuth credentials; grant least-privilege scopes needed
Use explicit spreadsheet IDs (from the URL) to avoid operating on the wrong file
Prefer range-specific reads/writes to limit bandwidth and avoid accidental overwrites
Validate and normalize data before writing to prevent schema drift in sheets
Use append for adding records and write (overwrite) only when replacing known ranges

Example use cases

Read a range like "Sheet1!A1:C10" to pull recent rows into a script
Append new transaction records into a monthly sheet without touching existing data
Create a new spreadsheet as a report template and populate headers and formulas
Add or delete tabs to reorganize data programmatically during ETL
Clear or overwrite a specific range to reset a dashboard section

FAQ

How do I find the spreadsheet ID?

Open the spreadsheet in a browser and copy the ID from the URL between /d/ and /edit.

What range formats are supported?

A1 notation is supported: specific ranges (Sheet1!A1:C10), full columns (Sheet1!A:C), rows (Sheet1!1:10), or a whole sheet name (Sheet1).