google-docs-automation

name	google-docs-automation
description	Use when agents need Google Workspace access across Drive, Docs, Sheets, Calendar, Slides, Tasks, People, or related GWS services; choose the correct gws-account profile before using gws CLI or domain-specific gws-* skills. Do not use Python gspread/googleapiclient or custom OAuth. Use msgvault for email search/reading.

Google Workspace Automation

Standard Approach: gws-bridge + gws Skills

This skill is not superseded by the gws-* skills. It is the umbrella entry point that tells agents how to choose the right Google Workspace account before using the domain-specific gws-drive, gws-docs, gws-calendar, gws-sheets, gws-slides, gws-tasks, and related skills.

gws-bridge is the standard for agent Google Workspace access. It preserves the gws service/resource/method surface while keeping account selection and credentials behind the host service. Use gws-account only for human administration and migration. Do not use raw gws from agents.

Choose the Profile First

Always select the profile by organization/context before running a command:

User phrase / domain	Profile	Account
Primary workspace or default company	primary	<[e-mail]> agent-safe artifact writes; no outbound send/invite
Explicit human-approved write/send/calendar mutation	primary-human	<[e-mail]> full write profile
Named client, project, or domain	configured profile	configured account
personal Gmail	personal	<[e-mail]>

Before acting, inspect the bridge:

gws-bridge health
gws-bridge profiles list

For a complete health check of every active profile, run braydon-workspace-skills/scripts/verify-all.sh.

If the bridge reports auth_required, stop and report the named profile. Do not attempt reauthentication or fall back to another account.

Email routing:

• Search, inspect, summarize, or read email history with msgvault, not gws.
• Agents should create email drafts through a configured draft-only workflow, then wait for human review.
• Use Gmail via GWS only for explicit live Gmail operations that are not covered by msgvault or the draft workflow, and confirm before sending or mutating mail.

Agent safety: The default agent profile may create/update Workspace artifacts such as Drive files, Docs, Sheets, Slides, Tasks, and contacts. It must not have Gmail send/modify scopes or Calendar write scopes. Do not use the human-write profile unless the user explicitly approves a live outbound send/calendar mutation. Google does not provide a Calendar draft-invite mode, and Gmail draft-capable API scopes also permit sending, so agents must not hold those outbound write scopes.

For email drafting, use the configured draft-only workflow:

curl -sS -X POST '<email-draft-webhook-url>' \
  -H 'Content-Type: application/json' \
  -d '{"to":"[e-mail]","subject":"Draft subject","body":"Draft body"}'

The workflow creates a Gmail draft for human review; it does not grant send permission to the agent.

See the gws-shared skill for global flags, syntax, and account details. See individual skills for each service: gws-drive, gws-docs, gws-calendar, gws-sheets, gws-slides, gws-tasks, and related GWS service skills.

Quick Reference

# List Drive files (include shared drive flags when needed)
gws-bridge primary drive files list --params '{"includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name,mimeType)"}'

# List a client Drive
gws-bridge client-a drive files list --params '{"includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name,mimeType)"}'

# List another workspace Drive
gws-bridge client-b drive files list --params '{"includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name,mimeType)"}'

# Search for docs by name
gws-bridge primary drive files list --params '{"q": "name contains '\''SOW'\''", "includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name)"}'

# Read a Google Doc
gws-bridge primary docs documents get --params '{"documentId": "<id>"}'

# Export a Google Doc as plain text
gws-bridge primary drive files export --params '{"fileId": "<id>", "mimeType": "text/plain"}'

# Search/read email history with msgvault, not GWS Gmail
MSGVAULT_HOME=<msgvault-home> ~/.local/bin/msgvault --home <msgvault-home> --config <msgvault-home>/config.toml search "subject:invoice" --json

# List calendar events
gws-bridge primary calendar events list --params '{"calendarId": "primary", "maxResults": 10}'

Do Not Use

• gspread / googleapiclient Python libraries — requires service account setup, adds code complexity
• Custom OAuth flows — gws handles auth
• GWS Gmail for email search/reading — use msgvault
• Direct SMTP/Gmail sending from agents — create draft artifacts for human review
• paia-os Gmail/GCal integration modules — legacy, ~4,900 lines of code that gws/msgvault/n8n replace