Google Docs Automation

Google Workspace Automation

Standard Approach: gws-account + 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-account is the standard for Google Workspace access. It wraps gws with the correct account profile. Do not use raw gws unless you explicitly set GOOGLE_WORKSPACE_CLI_CONFIG_DIR.

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 | ` agent-safe artifact writes; no outbound send/invite | | Explicit human-approved write/send/calendar mutation | primary-human | full write profile | | Named client, project, or domain | configured profile | configured account | | personal Gmail | personal | ` |

Before acting, inspect profiles:

gws-account list

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

If a profile reports auth_method: none or an auth failure, stop and report that the profile needs reauthorization before trying Drive/Docs/Calendar operations.

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 '' \
  -H 'Content-Type: application/json' \
  -d '{"to":"recipient@example.com","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-account primary drive files list --params '{"includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name,mimeType)"}'

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

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

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

# Read a Google Doc
gws-account primary docs documents get --params '{"documentId": ""}'

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

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

# List calendar events
gws-account 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dbmcco
• Source: dbmcco/claude-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.