gws_skill

Overview

This skill installs, configures, and operates gws — the Google Workspace CLI — to manage Gmail, Drive, Calendar, Sheets, Docs, Chat, Meet, Forms and more from the terminal. It guides users through auth setup with gcloud, enables APIs, and exposes composable commands and helpers that return structured JSON. Use it to automate workspace tasks, drive agent integrations, or connect Claude/other agents to Google services.

How this skill works

gws dynamically builds its command surface from Google’s Discovery Service so commands stay current without manual updates. After an interactive gcloud-based auth setup, gws exposes service commands (e.g., gmail, drive, calendar) and helper shortcuts (e.g., +send, +upload) that accept JSON params and return structured JSON. It can run an MCP server to surface workspace tools to agents and supports response sanitization to mitigate prompt-injection risks.

When to use it

• You want terminal-based access to Gmail, Drive, Calendar, Sheets, Docs, Chat, Meet, or Forms
• Automating email sends, inbox triage, calendar events, or Drive uploads via scripts or CI
• Connecting Claude or another agent to Workspace services via the MCP server
• Building reproducible CLI workflows that require structured JSON output
• Testing or integrating multiple Google Workspace APIs without writing custom SDK code

Best practices

• Run gws auth setup and gws auth login with gcloud already installed to avoid auth friction
• Use helper shortcuts (+send, +upload, +agenda) for common tasks; use raw service calls for advanced API usage
• Grant minimal OAuth scopes for personal workflows; use Full Access for dedicated agent/service accounts
• Limit MCP services to only those the agent needs to stay under tool limits
• Sanitize API responses (warn or block) when feeding email/doc content into agents to reduce prompt-injection risks

Example use cases

• Send RFC‑2822 formatted email from CI: gws gmail +send --to ... --subject ... --body ...
• Upload and share a report: gws drive +upload --file ./report.pdf --parent FOLDER_ID then create a permission
• Create calendar events and recurring standups via CLI or scripts: gws calendar +insert or events insert with JSON payload
• Read and append spreadsheet rows for ETL or reporting: gws sheets +read / +append with spreadsheet-id and ranges
• Run an MCP server to expose Drive, Gmail, Calendar tools to Claude with: gws mcp -s drive,gmail,calendar