# Google Workspace

> Manage Google Workspace with Docs, Sheets, Slides, Drive, Gmail, Calendar, and Contacts. Create professional documents, engaging presentations, reports from markdown. Convert markdown to Google Docs/Slides/PDF. Full editing, formatting, file management, email, and scheduling.

- **Type:** Skill
- **Install:** `agentstack add skill-andmarios-google-workspace-skill-google-workspace-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andmarios](https://agentstack.voostack.com/s/andmarios)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andmarios](https://github.com/andmarios)
- **Source:** https://github.com/andmarios/google-workspace-skill

## Install

```sh
agentstack add skill-andmarios-google-workspace-skill-google-workspace-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
```bash
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

```bash
# 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)
```bash
# 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:
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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`

2. **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

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

4. **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'
   ```

5. **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

6. **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

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

8. **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.

```bash
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.

```bash
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:
```bash
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

```bash
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`

```bash
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

```bash
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andmarios-google-workspace-skill-google-workspace-skill
- Seller: https://agentstack.voostack.com/s/andmarios
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.