Skip to content
LiveNew tools this week
Submit
AIMarketly
google-docs-automation logo

google-docs-automation

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 f...

dbmcco/claude-agent-toolkit0installs11starsProductivity & Planning

SKILL.md

Full skill instructions

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 / domainProfileAccount
Primary workspace or default companyprimary<[email protected]> agent-safe artifact writes; no outbound send/​invite
Explicit human-approved write/​send/​calendar mutationprimary-human<[email protected]> full write profile
Named client, project, or domainconfigured profileconfigured account
personal Gmailpersonal<[email protected]>

Before acting, inspect profiles:

<workspace-root>/​gws-profiles/​bin/​gws-account list

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 '<email-draft-webhook-url>' \
  -H 'Content-Type: application/​json' \
  -d '{"to":"[email protected]","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)
<workspace-root>/​gws-profiles/​bin/​gws-account primary drive files list --params '{"includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name,mimeType)"}'

# List a client Drive
<workspace-root>/​gws-profiles/​bin/​gws-account client-a drive files list --params '{"includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name,mimeType)"}'

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

# Search for docs by name
<workspace-root>/​gws-profiles/​bin/​gws-account primary drive files list --params '{"q": "name contains '\''SOW'\''", "includeItemsFromAllDrives": true, "supportsAllDrives": true, "fields": "files(id,name)"}'

# Read a Google Doc
<workspace-root>/​gws-profiles/​bin/​gws-account primary docs documents get --params '{"documentId": "<id>"}'

# Export a Google Doc as plain text
<workspace-root>/​gws-profiles/​bin/​gws-account 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
<workspace-root>/​gws-profiles/​bin/​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