Google Workspace

Google Workspace Skill

Manage Google Workspace documents, spreadsheets, presentations, drive files, emails, calendar events, and contacts via CLI.

Purpose

Google Docs: Read, create, export (markdown/pdf/docx/txt/html/rtf/epub/odt), insert/append text, find-replace, format (text, paragraph, extended), tables (insert, style, merge, row/column ops), headers/footers, lists/bullets, page breaks, section breaks, document styling, images, named range replacement

Google Sheets: Read, create, write/append data, full cell formatting (fonts, colors, alignment, number formats), borders, merge/unmerge cells, row/column sizing, freeze panes, conditional formatting, move rows/columns, copy-paste, auto-fill, trim whitespace, text-to-columns, chart updates

Google Slides: Read, create presentations, add/delete slides, text boxes, images, full text formatting (fonts, colors, effects, superscript/subscript, links), paragraph formatting (alignment, spacing, indentation), shapes (create and style), tables, element transforms (scale/rotate), grouping, alt text, Sheets chart embedding

Google Drive: Upload, download, search, share, create folders, move, copy, delete, comments, replies, shared drives, change tracking, revision management

Gmail: List, read, send, reply, search emails, history sync, batch label operations, label management

Calendar: List calendars, create/update/delete calendars, events, move events, color definitions, subscriptions

Contacts: List, create, update, delete contacts, groups, photos, directory search (Workspace), batch operations

Convert: Markdown to Google Docs, Slides, or PDF

When to Use

• User requests to read, create, or edit a Google Doc, Sheet, or Slides presentation
• User wants to upload, download, search, or share Drive files
• User wants to send, read, or search emails
• User wants to create or manage calendar events
• User wants to manage contacts
• User wants to convert Markdown to Google formats
• Keywords: "Google Doc", "spreadsheet", "presentation", "slides", "Drive", "upload", "share", "email", "calendar", "contacts"

Quick Start: Common Workflows

Create a professional document from markdown

uvx gws-cli convert md-to-doc /path/to/file.md -t "Document Title"

Create or enhance documents with rich content

When creating documents from scratch or enhancing converted documents, use all available tools:

• Image generation (DALL-E, etc.) - Create illustrations, diagrams, or infographics
• Diagram rendering - Use --render-diagrams flag or generate via Kroki
• Tables - Structure data clearly with insert-table and styling
• Charts/visualizations - Generate and insert as images

# Insert image into document
uvx gws-cli docs insert-image $DOC_ID "https://example.com/image.png" --index 50

# Or use diagram rendering during conversion
uvx gws-cli convert md-to-doc report.md -t "Report" --render-diagrams

Create an engaging presentation (manual approach recommended)

# 1. Create presentation
uvx gws-cli slides create "Presentation Title"

# 2. Add slides with layouts (TITLE, TITLE_AND_BODY, SECTION_HEADER, etc.)
uvx gws-cli slides add-slide $PRES_ID --layout TITLE_AND_BODY

# 3. Read to get element IDs
uvx gws-cli slides read $PRES_ID

# 4. Insert text into elements
uvx gws-cli slides insert-text $PRES_ID $ELEMENT_ID "Your content"

# 5. Apply styling
uvx gws-cli slides set-background $PRES_ID $SLIDE_ID --color "#1A365D"
uvx gws-cli slides format-text $PRES_ID $ELEMENT_ID --bold --font-size 24

Slide content limits (see [SKILL-advanced.md](SKILL-advanced.md) for design best practices)

• Maximum 6 bullet points per slide
• Maximum 6 words per bullet
• Under 40 words total per slide
• One idea per slide

Enhance presentations with visuals

Great presentations use images, diagrams, charts, and infographics to communicate ideas effectively. Use all available tools:

• Image generation (DALL-E, etc.) - Create custom illustrations, icons, or backgrounds
• Diagram tools (Mermaid, PlantUML) - Render flowcharts, architecture diagrams, timelines
• Charts from data - Visualize metrics and trends
• Screenshots/mockups - Show products, interfaces, or examples

Insert visuals with:

uvx gws-cli slides insert-image $PRES_ID $SLIDE_ID "https://example.com/image.png" \
    --x 100 --y 100 --width 400 --height 300

Send professional emails

# Simple email (short body as argument)
uvx gws-cli gmail send "recipient@example.com" "Subject" "Short message body"

# Multi-line email with heredoc (--stdin reads from pipe)
cat Project Status
Here's the latest update on our progress:

  Phase 1: Complete ✓
  Phase 2: In progress (80%)
  Phase 3: Scheduled for next week

Please review the full report.
EOF

Email formatting tips:

• Default is HTML - use `, , , ` tags
• No markdown-to-HTML conversion - provide HTML directly
• Use --plain for text-only emails (code samples, simple messages)

Search and filter emails

# Search with limit (--max or -n, default is 10)
uvx gws-cli gmail search "from:user@example.com" --max 5
uvx gws-cli gmail search "subject:invoice after:2025/01/01" -n 20

# Common search operators
uvx gws-cli gmail search "is:unread"                    # Unread messages
uvx gws-cli gmail search "has:attachment"               # Messages with attachments
uvx gws-cli gmail search "from:boss@company.com"        # From specific sender
uvx gws-cli gmail search "subject:urgent"               # Subject contains word
uvx gws-cli gmail search "after:2025/01/01"             # After date
uvx gws-cli gmail search "before:2025/02/01"            # Before date
uvx gws-cli gmail search "is:starred is:important"      # Combine operators

Key options:

• --max / -n: Limit results (default: 10)
• Search operators: from:, to:, subject:, is:, has:, after:, before:

Manage Drive files

# Upload a file
uvx gws-cli drive upload /path/to/file.pdf --name "Report Q1"

# Share with specific user
uvx gws-cli drive share  --email "colleague@company.com" --role writer

# Share with anyone who has link
uvx gws-cli drive share  --type anyone --role reader

# Search for files
uvx gws-cli drive search "name contains 'Report'" --max 10

# Download a file (screened for prompt injection; use --force to bypass)
uvx gws-cli drive download  /path/to/output.pdf

Schedule calendar events

# Create a simple event
uvx gws-cli calendar create "Team Meeting" "2025-01-15T10:00:00" "2025-01-15T11:00:00"

# Event with details and attendees
uvx gws-cli calendar create "Project Review" "2025-01-20T14:00:00" "2025-01-20T15:00:00" \
    --description "Quarterly review of project milestones" \
    --location "Conference Room A" \
    --attendees "alice@company.com,bob@company.com"

# All-day event
uvx gws-cli calendar create "Company Holiday" "2025-12-25" "2025-12-26" --all-day

# Recurring weekly meeting (COUNT goes in the RRULE string)
uvx gws-cli calendar create-recurring "Standup" "2025-01-06T09:00:00" "2025-01-06T09:15:00" \
    "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=52"

Calendar tips:

• Times use ISO 8601 format: YYYY-MM-DDTHH:MM:SS
• Use --all-day for date-only events (no time component)
• Descriptions are single-line only (no stdin support)

Work with spreadsheet data

# Create a spreadsheet
uvx gws-cli sheets create "Sales Report"

# Write data (simple)
uvx gws-cli sheets write  "A1:C1" --values '[["Name","Amount","Date"]]'

# Write complex data via stdin (avoids shell escaping)
cat  "A1:C4" --stdin
[
  ["Product", "Revenue", "Units"],
  ["Widget A", 15000, 500],
  ["Widget B", 22000, 440],
  ["Widget C", 8500, 170]
]
EOF

# Read data back
uvx gws-cli sheets read  "A1:C10"

# Append new rows
uvx gws-cli sheets append  "A:C" --values '[["Widget D", 12000, 300]]'

Sheets tips:

• JSON arrays use double brackets: [["row1col1","row1col2"],["row2col1","row2col2"]]
• Use --stdin for complex data to avoid shell escaping issues
• Sheet names with spaces: "Sheet Name!A1:B10" (double quotes)
• Use --formulas to read formulas instead of computed values

Safety Guidelines

Destructive operations - Always confirm with user before:

• Deleting documents, files, sheets, or slides (even to trash)
• Using docs replace (docs) or slides replace-text (slides), which affect ALL occurrences
• Deleting content ranges from documents
• Clearing spreadsheet ranges
• Sending emails
• Deleting calendar events or contacts

Best practices:

• Read document/spreadsheet/presentation first before modifying
• Show user what will change before executing
• Prefer append over write when adding new data
• Delete moves to trash by default (recoverable from Drive)
• For emails, confirm recipient and content before sending

Critical Rules

IMPORTANT - You MUST follow these rules:

1. Bullet lists in Markdown: ALWAYS use asterisks (*) NOT dashes (-) for bullet points. Google Docs API requires asterisks for proper list rendering. This applies to ALL markdown content being converted to Google Docs.

• CORRECT: * Item one
• WRONG: - Item one

1. Never modify original files: When converting Markdown to Google Docs, NEVER edit the user's original markdown file. Instead:

• Create a temporary copy in /tmp/ with the required formatting changes (e.g., converting - to * for bullets)
• Upload the temporary copy to Google Docs
• Delete the temporary file after successful upload
• This preserves the user's original file formatting

1. Read before modify: ALWAYS read the document first before making changes to understand structure and indices.

1. Use metadata for sheets: When working with spreadsheets that have multiple tabs, use uvx gws-cli sheets metadata FIRST to discover all sheet names and IDs. This avoids trial-and-error when reading specific sheets.

``bash # Get all sheet names in a spreadsheet uvx gws-cli sheets metadata # Then read a specific sheet # IMPORTANT: Use single quotes for the range to prevent bash history expansion uvx gws-cli sheets read 'Sheet Name!A1:Z100' ``

1. Never rewrite user content: When creating or converting documents:

• PRESERVE the user's exact text, words, and phrasing
• Only ADD formatting, structure, headers, footers
• NEVER rephrase, summarize, expand, or "improve" text
• If content changes are needed, ASK USER FIRST
• The user's words are sacred — apply styling only

1. Table consistency is mandatory: All tables in a document MUST have:

• Same border style and color
• Same header background color
• Same alignment conventions (text left, numbers right)
• Same cell padding
• See [SKILL-typesetting.md](SKILL-typesetting.md) for standards

1. Always add document structure: Every document should include:

• Header with document title
• Footer with page numbers
• Page breaks after major sections
• Proper heading hierarchy (H1, H2, H3 — not just bold)
• See [SKILL-typesetting.md](SKILL-typesetting.md) for complete guidelines

1. Images are standalone elements: When inserting images:

• NEVER place images inside bullet lists
• Images get their own paragraph with caption below
• Number figures sequentially (Figure 1, Figure 2)
• Reference by number ("See Figure 3"), not position ("see below")

Quick Reference

All commands use uvx gws-cli . Authentication is automatic on first use.

> Development mode: If working from a local checkout, use uv run gws-cli instead of uvx gws-cli.

Authentication

> Important: gws-cli auth and gws-cli auth --force open a browser for OAuth. These must be run by the user in their terminal, not from Claude Code.

uvx gws-cli auth              # Authenticate (opens browser)
uvx gws-cli auth status       # Check auth status
uvx gws-cli auth --force      # Force re-authentication (opens browser)
uvx gws-cli auth logout       # Logout
# Auth commands support --account for multi-account
uvx gws-cli auth status --account work

Credentials stored in ~/.config/gws-cli/ (client_secret.json, token.json, gws_config.json).

Multi-Account Support

Opt-in named accounts for different Google accounts. account add opens a browser — must be run by user.

uvx gws-cli account add work          # Add account (opens browser)
uvx gws-cli account update work --name "Jane Doe" --email "jane@company.com"
uvx gws-cli account list              # List all accounts
uvx gws-cli account default personal  # Change default
uvx gws-cli account remove work       # Remove account
uvx gws-cli account set-readonly work # Read-only mode (blocks writes)
uvx gws-cli account unset-readonly work

> Tip: Always set display name with account update --name "Full Name" after adding — it controls the email From field.

Using accounts: The -a/--account flag must come before the subcommand:

uvx gws-cli docs -a personal read        # Flag before subcommand
GWS_ACCOUNT=personal uvx gws-cli docs read   # Or via env var

Resolution: --account flag > GWS_ACCOUNT env var > default account > legacy mode

Services Reference

| Service | Ops | Reference | Description | |---------|-----|-----------|-------------| | drive | 28 | [reference/drive.md](reference/drive.md) | File upload, download, share, organize, comments, revisions, trash, permissions | | docs | 50 | [reference/docs.md](reference/docs.md) | Full document editing, export (md/pdf/docx/html/txt/rtf/epub/odt), tables, formatting, headers/footers, lists, named ranges, footnotes, suggestions | | sheets | 49 | [reference/sheets.md](reference/sheets.md) | Read, write, format, borders, merge, conditional formatting, charts, data validation, sorting, filters, pivot tables | | slides | 36 | [reference/slides.md](reference/slides.md) | Create, edit, shapes, tables, backgrounds, bullets, lines, cell merging, speaker notes, videos | | gmail | 35 | [reference/gmail.md](reference/gmail.md) | List, read, send, search, labels, drafts, attachments, threads, vacation, signatures, filters | | calendar | 23 | [reference/calendar.md](reference/calendar.md) | Manage events, recurring events, attendees, RSVP, free/busy, calendar sharing, reminders | | contacts | 15 | [reference/contacts.md](reference/contacts.md) | Manage contacts, groups, photos (People API) | | convert | 3 | (below) | Markdown to Docs/Slides/PDF |

Additional guides:

• [SKILL-typesetting.md](SKILL-typesetting.md) — Document formatting standards (fonts, tables, images, headers/footers, pagination)
• [SKILL-advanced.md](SKILL-advanced.md) — Content strategy, presentation storytelling, API efficiency

Document Conversion

uvx gws-cli convert md-to-doc /path/to/file.md --title "My Document"
uvx gws-cli convert md-to-slides /path/to/file.md --title "My Presentation"
uvx gws-cli convert md-to-pdf /path/to/file.md /path/to/output.pdf

> Limitation: md-to-slides lacks element ID mapping — styling can't be applied afterward. Use the manual approach in "Quick Start" for professional presentations.

Key options:

• --no-pageless — Traditional page-based layout (default is pageless/continuous)
• --render-diagrams / -d — Render diagram code blocks (Mermaid, PlantUML, GraphViz, D2, etc.) as images via Kroki API
• --mermaid-theme / -m — Theme for Mermaid diagrams: default, neutral, dark, forest

uvx gws-cli convert md-to-doc report.md -d --mermaid-theme neutral --no-pageless

Markdown requirements: Bullet lists MUST use asterisks (*) not dashes (-).

Slides parsing: # Heading = new slide, ## Sub = subtitle, - item = bullet, --- = slide break. Apply 6x6 rule (max 6 bullets, 6 words each).

Configuration

uvx gws-cli config list               # Show enabled se

…

## Source & license

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

- **Author:** [andmarios](https://github.com/andmarios)
- **Source:** [andmarios/google-workspace-skill](https://github.com/andmarios/google-workspace-skill)
- **License:** MIT

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