home / skills / abdullahbeam / nexus-design-abdullah / google-sheets

google-sheets skill

safe

This skill reads and writes Google Sheets data via OAuth, enabling seamless updates, appends, and retrieval for tracking and reporting.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill google-sheets

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

Files (2)

SKILL.md

3.9 KB

---
name: google-sheets
description: "Read and write Google Sheets data. Load when user mentions 'google sheets', 'spreadsheet', 'update sheet', 'read sheet', 'append to sheet', or references extracting data to update a tracking sheet."
version: 1.2
---

# Google Sheets

Read, write, and manage Google Sheets via OAuth authentication.

## Pre-Flight Check (ALWAYS FIRST)

```bash
python3 00-system/skills/google/google-master/scripts/google_auth.py --check --service sheets
```

**Exit codes:**
- **0**: Ready - proceed with user's request
- **1**: Need login - run `python3 00-system/skills/google/google-master/scripts/google_auth.py --login`
- **2**: Missing deps - see [../google-master/references/setup-guide.md](../google-master/references/setup-guide.md)

---

## Quick Reference

### Read Data
```bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py read <spreadsheet_id> "Sheet1!A1:D10"
```

### Write Data
```bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py write <spreadsheet_id> "Sheet1!A1" --values '[["Name", "Amount"], ["Contract A", 5000]]'
```

### Append Rows
```bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py append <spreadsheet_id> "Sheet1!A:D" --values '[["New Row", "Data", "Here", "Now"]]'
```

### Get Sheet Info
```bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py info <spreadsheet_id>
```

### List Spreadsheets
```bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py list --query "tracking"
```

### Create Spreadsheet
```bash
python3 00-system/skills/google/google-sheets/scripts/sheets_operations.py create "New Spreadsheet" --sheets "Data" "Summary"
```

---

## Common Workflows

### Extract Data -> Update Sheet

```python
from sheets_operations import append_rows

data = [
    ["Contract A", "2024-01-15", 5000, "Active"],
    ["Contract B", "2024-02-01", 7500, "Pending"]
]
result = append_rows(spreadsheet_id, "Contracts!A:D", data)
print(f"Added {result['updated_rows']} rows")
```

### Batch Update Multiple Cells

```python
from sheets_operations import batch_update

data = [
    {"range": "Sheet1!A1", "values": [["Header 1"]]},
    {"range": "Sheet1!B1", "values": [["Header 2"]]},
]
batch_update(spreadsheet_id, data)
```

---

## Spreadsheet ID

The spreadsheet ID is in the URL:
```
https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit
```

---

## A1 Notation

| Example | Meaning |
|---------|---------|
| `A1` | Single cell |
| `A1:B5` | Range from A1 to B5 |
| `Sheet1!A1:B5` | Range in specific sheet |
| `A:A` | Entire column A |
| `1:1` | Entire row 1 |

---

## Available Operations

| Operation | Function | Description |
|-----------|----------|-------------|
| **Read** | `read_range()` | Read data from range |
| **Write** | `write_range()` | Write data to range |
| **Append** | `append_rows()` | Append rows to sheet |
| **Clear** | `clear_range()` | Clear values (keep formatting) |
| **Batch** | `batch_update()` | Update multiple ranges |
| **Create** | `create_spreadsheet()` | Create new spreadsheet |
| **Info** | `get_spreadsheet_info()` | Get metadata and sheets |
| **List** | `list_spreadsheets()` | List accessible spreadsheets |

---

## Error Handling

See [../google-master/references/error-handling.md](../google-master/references/error-handling.md) for common errors and solutions.

---

## Setup

First-time setup: [../google-master/references/setup-guide.md](../google-master/references/setup-guide.md)

**Quick start:**
1. `pip install google-auth google-auth-oauthlib google-api-python-client`
2. Create OAuth credentials in Google Cloud Console (enable Google Sheets API & Drive API, choose "Desktop app")
3. Add to `.env` file at Nexus root:
   ```
   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_PROJECT_ID=your-project-id
   ```
4. Run `python3 00-system/skills/google/google-master/scripts/google_auth.py --login`

Overview

This skill reads, writes, and manages Google Sheets using OAuth-authenticated API calls. It exposes common operations like read, write, append, batch update, create, list, and metadata retrieval. The skill is designed for automation scripts that push or pull tabular data between services and tracking spreadsheets.

How this skill works

It uses Google OAuth credentials to authenticate with the Sheets and Drive APIs. Scripts call functions such as read_range(), write_range(), append_rows(), batch_update(), create_spreadsheet(), get_spreadsheet_info(), and list_spreadsheets() to perform operations on ranges specified in A1 notation. A pre-flight auth check confirms login and dependency status before any operation.

When to use it

Extracting data from an app or report and appending it to a tracking or ledger sheet
Updating headers, status columns, or financial figures in a spreadsheet programmatically
Bulk-writing or batch-updating multiple non-contiguous ranges in one request
Creating new spreadsheets for automated reports or dashboards
Listing accessible spreadsheets to find the correct spreadsheet ID for automation

Best practices

Always run the pre-flight auth check to ensure OAuth tokens and dependencies are available
Use A1 notation consistently (SheetName!A1:B5) to avoid range ambiguity
Prefer batch_update for multiple discrete writes to reduce API calls and improve performance
Sanitize and validate data before writing or appending to avoid corrupting rows
Store OAuth credentials and client secrets in environment variables or a secure vault

Example use cases

Append extracted contract rows to a central Contracts sheet using append_rows(spreadsheet_id, 'Contracts!A:D', data)
Read a report range to transform and load into a BI tool using read_range() then export
Batch update header labels and status flags across sheets with batch_update() in one call
Create a new monthly report spreadsheet programmatically with create_spreadsheet('Monthly Report')
List spreadsheets with a keyword query to locate the right tracking file before performing updates

FAQ

How do I find the spreadsheet ID?

The spreadsheet ID is the part of the URL between /d/ and /edit (https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit).

What should I do if the auth check exits with code 1 or 2?

Exit code 1 means you need to run the login step to authenticate. Exit code 2 indicates missing dependencies—install the required Python packages and follow the setup guide.