google-workspace

name	google-workspace
version	1.0.0
description	Interact with Google Calendar, Drive, Docs, and Sheets via Google APIs. Create events, manage files, edit documents, and query spreadsheets. Use this skill when the user mentions Google Calendar, Google Drive, Google Docs, Google Sheets, or needs to interact with Google Workspace. Also trigger for "gcal", "gdrive", "gsheet", "google doc", "google calendar", "google drive", "schedule a meeting" (if they use Google), or "create a spreadsheet in Google."
author	G-HunterAi
license	MIT
tags	["google","calendar","drive","docs","sheets","workspace"]
platforms	["all"]
category	integration
metadata	{"clawdbot":{"emoji":"🔷","secrets":[{"name":"GOOGLE_CLIENT_ID","description":"OAuth 2.0 client ID from Google Cloud Console"},{"name":"GOOGLE_CLIENT_SECRET","description":"OAuth 2.0 client secret"}]}}

Google Workspace Skill

Unified integration for Google Calendar, Drive, Docs, and Sheets. Use a single OAuth2 flow to manage your entire Google Workspace ecosystem.

When to Use / When NOT to Use

Use for:

• Creating and managing Google Calendar events
• Google Drive file operations (upload, organize, share)
• Editing Google Docs and formatting documents
• Reading and writing Google Sheets data

NOT for:

• Apple Calendar integration (use apple-calendar)
• Local file management (access your computer filesystem)
• Non-Google email (use email-automation for generic SMTP)

Quick Start

1. Setup Credentials

1. Visit Google Cloud Console
2. Create a new project
3. Enable APIs: Calendar, Drive, Docs, Sheets
4. Create OAuth2 credentials (Desktop/Web application)
5. Set authorized redirect URI: http://localhost:8080/auth/callback
6. Save GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET as secrets

2. Authenticate

authenticate_google_workspace()

Performs OAuth2 handshake once. Token stored securely for future requests.

Calendar Operations

Create Event

create_calendar_event(
    title: str,
    start_time: str,  # ISO 8601: "2026-03-25T14:00:00Z"
    end_time: str,
    description: str = "",
    attendees: list[str] = [],
    location: str = "",
    reminder_minutes: int = 15
)

Example: Schedule a team standup.

create_calendar_event(
    title="Team Standup",
    start_time="2026-03-25T09:00:00-07:00",
    end_time="2026-03-25T09:30:00-07:00",
    attendees=["[e-mail]", "[e-mail]"],
    location="Conference Room A",
    reminder_minutes=10
)

List Events

list_calendar_events(
    days_ahead: int = 7,
    calendar_id: str = "primary"
)

Returns events for the next N days.

Update Event

update_calendar_event(
    event_id: str,
    title: str = None,
    start_time: str = None,
    end_time: str = None,
    description: str = None
)

Delete Event

delete_calendar_event(event_id: str)

Drive Operations

Create File

create_drive_file(
    name: str,
    file_type: str,  # "folder", "doc", "sheet", "file"
    parent_folder_id: str = "root",
    content: bytes = None
)

Returns file_id for created file.

List Files

list_drive_files(
    parent_folder_id: str = "root",
    name_contains: str = "",
    file_type: str = None  # "folder", "doc", "sheet", etc.
)

Share File

share_drive_file(
    file_id: str,
    email: str,
    role: str = "reader"  # "reader", "commenter", "editor"
)

Move/Copy File

move_drive_file(file_id: str, new_parent_id: str)
copy_drive_file(file_id: str, name: str = None)

Delete File

delete_drive_file(file_id: str)

Docs Operations

Create Document

create_docs_document(
    title: str,
    folder_id: str = "root"
)

Returns doc_id and doc_url.

Insert Content

insert_docs_content(
    doc_id: str,
    text: str,
    position: int = None  # Default: append
)

Format Document

format_docs_text(
    doc_id: str,
    start_index: int,
    end_index: int,
    bold: bool = False,
    italic: bool = False,
    font_size: int = None,
    color: str = None  # Hex: "#FF0000"
)

Example: Create and format a meeting notes document.

doc_id = create_docs_document("Q1 Planning Notes")
insert_docs_content(doc_id, "Meeting: March 25, 2026\n\nAttendees:\n")
format_docs_text(doc_id, 0, 8, bold=True, font_size=14)

Get Document

get_docs_content(doc_id: str)

Returns full document text and metadata.

Sheets Operations

Create Spreadsheet

create_sheets_spreadsheet(
    title: str,
    folder_id: str = "root"
)

Returns sheet_id and sheet_url.

Write Data

write_sheets_data(
    sheet_id: str,
    range_name: str,  # "Sheet1!A1:C5" or "A1"
    values: list[list],
    mode: str = "OVERWRITE"  # "OVERWRITE", "APPEND"
)

Example: Create a sales tracker spreadsheet.

sheet_id = create_sheets_spreadsheet("Q1 Sales")
write_sheets_data(
    sheet_id,
    "Sheet1!A1:D1",
    [["Date", "Deal", "Amount", "Stage"]]
)
write_sheets_data(
    sheet_id,
    "Sheet1!A2:D4",
    [
        ["2026-03-20", "Acme Corp", "$50k", "Proposal"],
        ["2026-03-19", "Tech Inc", "$120k", "Negotiation"],
        ["2026-03-18", "Global Ltd", "$75k", "Discovery"]
    ]
)

Read Data

read_sheets_data(
    sheet_id: str,
    range_name: str
)

Returns 2D array of cell values.

Query Sheets (Filter/Sort)

query_sheets_data(
    sheet_id: str,
    sheet_name: str,
    where: dict = None,  # {"column": "value"}
    order_by: str = None,
    limit: int = None
)

Add Charts

create_sheets_chart(
    sheet_id: str,
    title: str,
    data_range: str,  # "Sheet1!A1:B10"
    chart_type: str  # "LINE", "BAR", "PIE", "AREA"
)

Error Handling

All operations raise descriptive exceptions:

try:
    create_calendar_event(...)
except GoogleAuthError:
    print("Token expired or invalid. Reauthenticate.")
except GoogleAPIError as e:
    print(f"API error: {e.message}")
except RateLimitError:
    print("Quota exceeded. Retry in 60 seconds.")

Best Practices

1. Token Refresh: Automatically handles token refresh. No manual intervention needed.
2. Rate Limiting: Built-in exponential backoff for quota errors.
3. Batch Operations: Use batch_write_sheets_data() for large datasets.
4. Folder Organization: Store folder_id references for repeated access.
5. Timezone Handling: Always use ISO 8601 format with timezone offset.

Works Well With

• apple-calendar — Sync events between Google and Apple for full calendar coverage
• email-automation — Gmail integration and create calendar events from emails
• data-analysis — Use Sheets as a data source for analysis pipelines
• doc-converter — Convert Google Docs to other formats (PDF, Markdown, etc.)

Integration Points

• apple-calendar: Sync events between Google and Apple Calendar
• email-automation: Create calendar events from email reminders
• data-analysis: Query Sheets data for analysis pipelines

Limitations

• Calendar API limited to primary calendar (personal calendar)
• Large files (>100MB) use resumable uploads (automatic)
• Sheets API: 500 requests per 100 seconds per user
• Document size limit: 50MB

See Also

• Calendar Reference
• Drive Reference
• Docs Reference
• Sheets Reference