---

name: google-workspace description: Access Google Workspace APIs (Drive, Docs, Calendar, Gmail, Sheets, Slides, People) via local helper scripts. Handles OAuth login and direct API calls. USE WHEN user wants to search Google Drive, check calendar, search Gmail, read Google Docs, or interact with any Google Workspace service.

Google Workspace

Access Google Workspace APIs from the agent via local Node.js helper scripts — no MCP server needed.

Supports: Drive, Docs, Calendar, Gmail, Sheets, Slides, People.

Files

All scripts live in the skill directory:

• scripts/auth.js — login / status / clear token
• scripts/workspace.js — call APIs (generic and convenience commands)
• scripts/common.js — shared auth logic

Script base directory: ~/.config/claude/skills/GoogleWorkspace/scripts

One-Time Setup

1. Create OAuth Credentials

1. Go to Google Cloud Console → Credentials
2. Create an OAuth 2.0 Client ID (type: Desktop app)
3. Download the JSON and save it to:

~/.config/google-workspace/credentials.json

4. Enable these APIs in your Google Cloud project:
   • Google Calendar API
   • Google Drive API
   • Gmail API
   • Google Docs API
   • Google Sheets API
   • Google Slides API
   • People API

2. Install Dependencies

Dependencies auto-install on first script run. To prewarm manually:

cd ~/.config/claude/skills/GoogleWorkspace/scripts
npm install

3. Authenticate

cd ~/.config/claude/skills/GoogleWorkspace/scripts
node auth.js login

This opens the browser for OAuth consent. Token is stored at ~/.config/google-workspace/token.json.

Operational Guidance for the Agent

1. Always check auth first: Run node auth.js status before making API calls.
2. If auth is missing/expired: Run node auth.js login and wait for the user to complete browser consent.
3. Do not explain setup unless a command actually failed and its error output requires user action.
4. Use workspace.js call for precise operations and return raw JSON results.
5. For user-friendly output: Post-process JSON after the call — summarize, format tables, extract key info.
6. Never print token contents back to the user.
7. Always cd into the scripts directory before running commands.

API Usage

Generic API Call

cd ~/.config/claude/skills/GoogleWorkspace/scripts
node workspace.js call <service> <method.path> '<json params>'

Services: drive, docs, calendar, gmail, sheets, slides, people

Examples:

# List 5 Drive files
node workspace.js call drive files.list '{"pageSize":5,"fields":"files(id,name)"}'

# Get today's calendar events
node workspace.js call calendar events.list '{"calendarId":"primary","maxResults":10,"singleEvents":true,"orderBy":"startTime"}'

# Get a Google Doc
node workspace.js call docs documents.get '{"documentId":"<DOC_ID>"}'

# List Gmail labels
node workspace.js call gmail users.labels.list '{"userId":"me"}'

# Read a spreadsheet
node workspace.js call sheets spreadsheets.values.get '{"spreadsheetId":"<SHEET_ID>","range":"Sheet1!A1:D10"}'

Convenience Commands

cd ~/.config/claude/skills/GoogleWorkspace/scripts

# Today's calendar events
node workspace.js calendar-today

# Next N days of events (default: 7)
node workspace.js calendar-upcoming 3

# Search Google Drive
node workspace.js drive-search "name contains 'Roadmap' and trashed=false"

# Search Gmail
node workspace.js gmail-search "from:alice@example.com newer_than:7d"

# Read a specific Gmail message (full body)
node workspace.js gmail-read <messageId>

Auth Commands

cd ~/.config/claude/skills/GoogleWorkspace/scripts

# Check auth status
node auth.js status

# Login (opens browser)
node auth.js login

# Clear stored token
node auth.js clear

Environment Overrides

Variable	Default	Description
GOOGLE_WORKSPACE_CONFIG_DIR	~/.config/google-workspace	Config directory
GOOGLE_WORKSPACE_CREDENTIALS	<config_dir>/credentials.json	OAuth credentials file
GOOGLE_WORKSPACE_TOKEN	<config_dir>/token.json	Stored token file

Common Google API Patterns

Drive: Search by type

node workspace.js drive-search "mimeType='application/vnd.google-apps.document'"
node workspace.js drive-search "mimeType='application/vnd.google-apps.spreadsheet'"
node workspace.js drive-search "mimeType='application/vnd.google-apps.presentation'"

Drive: Recent files

node workspace.js call drive files.list '{"pageSize":10,"orderBy":"modifiedTime desc","fields":"files(id,name,mimeType,modifiedTime,webViewLink)"}'

Gmail: Common queries

node workspace.js gmail-search "is:unread newer_than:1d"
node workspace.js gmail-search "has:attachment newer_than:7d"
node workspace.js gmail-search "in:sent newer_than:1d"

Calendar: Specific calendar

node workspace.js calendar-today "work@redhat.com"