claude-configs/skills/gws/SKILL.md

name	description
gws	Google Workspace CLI for Drive, Sheets, Gmail, and Calendar. USE WHEN user mentions "spreadsheet", "google sheets", "google drive", "gmail", "google calendar", "gws", or wants to read/write/create Google Workspace documents.

GWS - Google Workspace CLI

SCOPE: Use when interacting with Google Drive, Sheets, Gmail, or Calendar via the gws CLI.

When to Activate

• "update the spreadsheet", "read the sheet", "add a row"
• "create a spreadsheet", "make a Google Sheet"
• "check my email", "search Gmail"
• "list my Drive files", "find a file in Drive"
• "check my calendar", "list events"
• Any task involving a Google Sheets spreadsheet ID

Quick Reference

All commands run via Bash. Output is JSON by default. Add --format table for human-readable output.

Sheets (most common)

# Read a range
gws sheets +read --spreadsheet "$ID" --range 'Sheet1!A1:D10'

# Append a row
gws sheets +append --spreadsheet "$ID" --values 'val1,val2,val3'

# Append multiple rows
gws sheets +append --spreadsheet "$ID" --json-values '[["a","b"],["c","d"]]'

# Update specific cells
gws sheets spreadsheets values update \
  --params "{\"spreadsheetId\": \"$ID\", \"range\": \"Sheet1\u0021A1:B2\", \"valueInputOption\": \"USER_ENTERED\"}" \
  --json '{"values": [["new1","new2"],["new3","new4"]]}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "My Sheet"}}'

# Clear a range
gws sheets spreadsheets values clear \
  --params "{\"spreadsheetId\": \"$ID\", \"range\": \"Sheet1\u0021A1:Z100\"}"

Drive

# List files
gws drive files list --params '{"pageSize": 10}'

# Search files
gws drive files list --params '{"q": "name contains \"keyword\""}'

Gmail

# Unread messages
gws gmail users messages list --params '{"userId": "me", "q": "is:unread"}'

Calendar

# Upcoming events
gws calendar events list --params '{"calendarId": "primary", "maxResults": 5}'

Critical Gotchas

1. ! in ranges — In double-quoted JSON, use \u0021 instead of ! (bash history expansion breaks it). Single-quoted JSON is safe: 'Sheet1!A1:B2'
2. --params vs --json — URL/query params (spreadsheetId, range, valueInputOption) go in --params. Request body (values, properties) goes in --json
3. valueInputOption — Required for writes. Use USER_ENTERED (parses formulas/numbers) or RAW (literal strings)
4. Helpers vs raw API — +read and +append are convenient shortcuts. For updates, batch operations, or clearing, use the raw spreadsheets values subcommands

Auth & Config

• OAuth credentials encrypted in OS keyring
• Config dir: ~/.config/gws/
• Authenticated scopes: drive, gmail, calendar, sheets
• Add --dry-run to any command to validate without sending
• Introspect any API method: gws schema sheets.spreadsheets.values.update

Output Formats

--format json (default) | --format table | --format csv | --format yaml

Detailed Examples (load on demand)

Product	File
Sheets	~/.claude/skills/gws/examples-sheets.md — batch update/get, add/rename/delete tabs, formatting, freeze rows
Drive	~/.claude/skills/gws/examples-drive.md — search, MIME filters, folder listing, pagination
Gmail	~/.claude/skills/gws/examples-gmail.md — search filters, read messages
Calendar	~/.claude/skills/gws/examples-calendar.md — date ranges, create events, all-day events