Agent-Skills.md

Agent Skills: Google Workspace Automation

Use when automating Google Workspace (Docs, Sheets, Slides) operations - covers authentication, common patterns, and best practices for gspread and googleapiclient

UncategorizedID: dbmcco/claude-agent-toolkit/google-docs-automation

Repository

dbmcco/claude-agent-toolkit
dbmccoLicense: MIT
81

Install this agent skill to your local

pnpm dlx add-skill https://github.com/dbmcco/claude-agent-toolkit/tree/HEAD/skills/google-docs-automation

Skill Files

Browse the full folder contents for google-docs-automation.

Download Skill

Loading file tree…

skills/google-docs-automation/SKILL.md

Skill Metadata

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

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":"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)
<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