google-workspace

Manage Gmail, Calendar, Drive, Sheets, and Docs via OAuth-authenticated CLI and Python API calls.

1|Updated Jun 21, 2026
One-click install
npx skills add https://github.com/tapway/shogun-os --skill google-workspace-tapway
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: google-workspace
Source: https://github.com/tapway/shogun-os/tree/main/skills/workspace/google-workspace
Command: npx skills add https://github.com/tapway/shogun-os --skill google-workspace-tapway

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires google-api-python-client, google-auth, and includes scripts (resource) and references (resource) components.

What problem does it solve? Connecting an AI agent to Google Workspace normally requires juggling OAuth flows, scope management, token refresh, and inconsistent API behaviors across Gmail, Calendar, Drive, Sheets, and Docs. This Skill provides a single authenticated CLI wrapper and Python client that returns consistent JSON for every service, with guided setup for both individual OAuth and Domain-Wide Delegation. ## Core Features & Use Cases - Gmail operations: Search with Gmail query syntax, read full messages, send plain or HTML email, reply with proper threading, and manage labels. - Calendar management: List and create events on primary or shared calendars with timezone-aware ISO 8601 times, plus decline events via direct API patterns. - Drive, Sheets, and Docs access: Search Drive files, read/write/append Sheets ranges, read Docs, and write Docs via batchUpdate REST patterns including shared drive and IRM-restricted file workarounds. - Use Case: Ask the agent for a digest of unread email, then have it create a follow-up calendar event and log action items into a Google Sheet — all through one authenticated token. ## Quick Start Ask the agent to check Google Workspace authentication with setup.py --check and then list your next seven days of calendar events.

Frequently Asked Questions about google-workspace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search and read Gmail messages from the command line?

Use the google_api.py wrapper with commands like gmail search "is:unread" --max 10 to get a JSON array of matching messages, then gmail get MESSAGE_ID to read the full body. Authentication uses a token at ~/.hermes/google_token.json created by the bundled setup.py script.

How do I write to a Google Doc using the API?

The wrapper only supports docs get for reading. To write, use direct REST calls to the Docs batchUpdate endpoint with deleteContentRange and insertText requests, requiring the https://www.googleapis.com/auth/documents scope. The references/docs-batch-update.md guide covers full replace, append, and styling patterns.

Can I access Google Shared Drives with the Google Drive API?

Yes, but the google_api.py wrapper does not pass supportsAllDrives or includeItemsFromAllDrives, so shared drive files return 404. Use direct Python REST calls with supportsAllDrives=True, includeItemsFromAllDrives=True, and corpora=allDrives as documented in references/shared-drive-access.md.

Why does my Google OAuth token keep expiring or showing invalid_grant?

Common causes are a token file saved in raw OAuth response format instead of the Credentials format, or a refresh token expired after inactivity or Testing-mode consent screen expiry. Fix format issues by rewriting the token keys, or set up the token watchdog cron in references/google-token-watchdog.md.

When should I use Domain-Wide Delegation instead of individual OAuth?

Use Domain-Wide Delegation when a service account needs to impersonate users across a Google Workspace domain without per-user consent screens. It uses a service account key at ~/.hermes/secrets/google-dwd-sa.json with a subject field, as covered in references/google-dwd-setup.md.

What are the limitations of the google_api.py wrapper for Sheets?

The wrapper supports only sheets get, update, and append — there is no sheets create command. To create a spreadsheet, use a direct Python script against the Sheets API per references/sheets-create.md, and always discover actual tab names first to avoid 400 Unable to parse range errors.