google-workspace-skills - SKILL.md Agent Skill

name: google-workspace-skills description: Access Gmail and Google Calendar via the Google APIs. Use when checking email, reading messages, sending emails, viewing calendar events, checking availability, or creating/modifying calendar events. Requires OAuth setup - see references/setup.md.

Google Workspace Skills

Access Gmail and Google Calendar through TypeScript scripts using OAuth2 with PKCE authentication.

Setup

Before first use, complete OAuth setup. See references/setup.md for detailed instructions:

Create Google Cloud project and enable Gmail + Calendar APIs
Configure OAuth consent screen with required scopes
Create Desktop OAuth credentials
Save credentials.json to ~/.openclaw/credentials/google/
Run cd scripts && npm install && npx tsx auth.ts

Gmail Operations

Check for new/unread messages

npx tsx scripts/gmail-list.ts --unread

List recent inbox messages

npx tsx scripts/gmail-list.ts --max 10

Search messages

npx tsx scripts/gmail-list.ts --query "from:boss subject:urgent"
npx tsx scripts/gmail-list.ts --query "is:unread after:2024/01/01"

Read message content

npx tsx scripts/gmail-read.ts <message-id>

Send email

npx tsx scripts/gmail-send.ts --to "recipient@example.com" --subject "Hello" --body "Message text"

Reply to message

npx tsx scripts/gmail-send.ts --reply-to <message-id> --body "Thanks for your message"

Calendar Operations

View today's events

npx tsx scripts/calendar-list.ts --today

View this week's events

npx tsx scripts/calendar-list.ts --week

View specific date or range

npx tsx scripts/calendar-list.ts --date 2024-01-15
npx tsx scripts/calendar-list.ts --from 2024-01-01 --to 2024-01-31

Create event

# Timed event
npx tsx scripts/calendar-create.ts --summary "Team Meeting" --start "2024-01-15T10:00" --duration 60

# All-day event
npx tsx scripts/calendar-create.ts --summary "Conference" --date "2024-01-20"

# With attendees and location
npx tsx scripts/calendar-create.ts --summary "Sync" --start "2024-01-15T14:00" --end "2024-01-15T15:00" \
    --attendees "a@example.com,b@example.com" --location "Room 101"

Update event

npx tsx scripts/calendar-update.ts <event-id> --summary "New Title"
npx tsx scripts/calendar-update.ts <event-id> --start "2024-01-15T11:00"
npx tsx scripts/calendar-update.ts <event-id> --add-attendees "new@example.com"

Cancel event

npx tsx scripts/calendar-update.ts <event-id> --cancel

Script Reference

Script	Purpose
`auth.ts`	OAuth authentication with PKCE
`gmail-list.ts`	List/search Gmail messages
`gmail-read.ts`	Read message content
`gmail-send.ts`	Send or reply to emails
`calendar-list.ts`	List calendar events
`calendar-create.ts`	Create new events
`calendar-update.ts`	Update or cancel events

All scripts support --help for full option details.

Output Format

Scripts output both human-readable text and JSON. The JSON section (after --- JSON ---) can be parsed for programmatic use.

Authentication

Tokens are stored at ~/.openclaw/credentials/google/token.json
Tokens refresh automatically when expired
Check status: npx tsx scripts/auth.ts --check
Re-authenticate: npx tsx scripts/auth.ts
Revoke: npx tsx scripts/auth.ts --revoke