git:20260611.7e4abf6 to git:20260626.d9fb956

10 added, 3 removed. Audit A to A.

---

name: google-workspace

description: "Use when accessing Google Workspace services including Gmail, Calendar, Docs, Sheets, Slides, Drive, and Chat. Triggered by requests for email, scheduling, document creation, or file management."

allowed-tools: Read, Write, Edit, Bash, WebFetch

user-invocable: true

---

# Google Workspace Extension - Behavioral Guide

This guide provides behavioral instructions for effectively using the Google Workspace Extension tools. For detailed parameter documentation, refer to the tool descriptions in the extension itself.

+ ## Repo Context Probe

+ If `.claude/skill-context/google-workspace.md` exists, read it and honor its declarations; otherwise use the generic defaults described below.

+ The context file is where a repo declares a faster project-local mail CLI to try *above* the generic Gmail ladder. When the file is absent (the common case in a foreign repo), start the mail ladder at `gws gmail` — the generic tiers below need nothing beyond a Google Workspace login or an interactive MCP session.

## 🧭 Tool Selection (read this first)

Reach for the lightest tool that does the job. For every service, walk the

priority order below top to bottom: try the `gws` CLI first, fall through to MCP

only on tool absence OR auth failure, and use BYOB browser automation only as a

last resort when nothing above can do the task at all. A present-but-

unauthenticated `gws` (it needs a one-time `gws auth setup` / `gws auth login`

human OAuth step) must hand off to the next tier — do not stall on it.

|---------|----------------|----------------------------|-------------------|

- For reading/sending mail specifically, prefer the `/email` skill's ladder

- (`valor-email` → `gws gmail` → Gmail MCP → BYOB), which puts the Redis-cached

- `valor-email` CLI ahead of `gws`.

+ For reading/sending mail specifically, prefer the `/email` skill's ladder, which

+ starts at `gws gmail` → Gmail MCP → BYOB. If the repo context file declares a

+ faster project-local mail CLI, the `/email` skill puts it ahead of `gws` as Tier 1;

+ otherwise the generic `gws gmail` tier is the top of the mail ladder.

## 🎯 Core Principles

### 1. User Context First

**Always establish user context at the beginning of interactions:**

- Use `gws people people get --params '{"resourceName": "people/me"}'` to understand who the user is

- Establish the user's local timezone (e.g. `gws calendar settings get --params '{"setting": "timezone"}'`)

- Apply this context throughout all interactions

- All time-based operations should respect the user's timezone

### 2. Safety and Transparency

**Never execute write operations without explicit confirmation:**

- Preview all changes before executing

- Show complete details in a readable format

- Wait for clear user approval

- Give users the opportunity to review and cancel

### 3. Smart Tool Usage

**Choose the right approach for each task:**

- Tools automatically handle URL-to-ID conversion - don't extract IDs manually

- Batch related operations when possible

- Use pagination for large result sets

- Apply appropriate formats based on the use case

## 📋 Output Formatting Standards

### Lists and Search Results

Always format multiple items as **numbered lists** for better readability:

✅ **Correct:**

```

Found 3 documents:

1. Budget Report 2024

2. Q3 Sales Presentation

3. Team Meeting Notes

```

❌ **Incorrect:**

```

Found 3 documents:

- Budget Report 2024

- Q3 Sales Presentation

- Team Meeting Notes

```

### Write Operation Previews

Before any write operation, show a clear preview:

```

I'll create this calendar event:

Title: Team Standup

Date: January 15, 2025

Time: 10:00 AM - 10:30 AM (EST)

Attendees: team@example.com

Should I create this event?

```

## 🔄 Multi-Tool Workflows

### Creating and Organizing Documents

When creating documents in specific folders:

1. Create the document first

2. Then move it to the folder (if specified)

3. Confirm successful completion

### Calendar Scheduling Workflow

1. Establish the user's timezone (see User Context First)

2. Check availability with `gws calendar events list` (or `mcp__claude_ai_Google_Calendar__list_events`)

3. Create event with proper timezone handling

4. Always show times in user's local timezone

### Email Search and Response

1. Search with `gws gmail users messages list` using Gmail query syntax (or `mcp__claude_ai_Gmail__search_threads`)

2. Get full content with `gws gmail users messages get` if needed (or `mcp__claude_ai_Gmail__get_thread`)

3. Preview any reply before sending

4. Use threading context when responding

### Adding/Removing Labels from Emails

1. For system labels, including "INBOX", "SPAM", "TRASH", "UNREAD", "STARRED", "IMPORTANT", the ID is the name itself.

2. For user created custom labels, retrieve label ID with `gws gmail users labels list` (or `mcp__claude_ai_Gmail__list_labels`).

3. Use `gws gmail users messages modify` to add or remove labels from emails with a single call using label IDs (or `mcp__claude_ai_Gmail__label_message` / `mcp__claude_ai_Gmail__unlabel_message`).

### Event Deletion

When deleting a calendar event (`gws calendar events delete`, or `mcp__claude_ai_Google_Calendar__delete_event`):

- This is a destructive action that permanently removes the event.

- For organizers, this cancels the event for all attendees.

- For attendees, this only removes it from their own calendar.

- Always confirm with the user before executing a deletion.

## 📅 Calendar Best Practices

### Understanding "Next Meeting"

When asked about "next meeting" or "today's schedule":

1. **Fetch the full day's context** - Use start of day (00:00:00) to end of day (23:59:59)

2. **Filter by response status** - Only show meetings where the user has:

- Accepted the invitation

- Not yet responded (needs to decide)

- DO NOT show declined meetings unless explicitly requested

3. **Compare with current time** - Identify meetings relative to now

4. **Handle edge cases**:

- If a meeting is in progress, mention it first

- "Next" means the first meeting after current time

- Keep full day context for follow-up questions

### Meeting Response Filtering

- **Default behavior**: Show only accepted and pending meetings

- **Declined meetings**: Exclude unless user asks "show me all meetings" or "including declined"

- **Use `attendeeResponseStatus`** parameter to filter appropriately

- This respects the user's time by not cluttering their schedule with irrelevant meetings

### Timezone Management

- Always display times in the user's timezone

- Convert all times appropriately before display

- Include timezone abbreviation (EST, PST, etc.) for clarity

## 📧 Gmail & Chat Guidelines

### Search Strategies

- Use Gmail search syntax: `from:email@example.com is:unread`

- Combine multiple criteria for precise results

- Include SPAM/TRASH only when explicitly needed

### Threading and Context

- Maintain conversation context in replies

- Reference previous messages when relevant

- Use appropriate reply vs. new message based on context

### Downloading Attachments

1. **Find Attachment ID**: Use `gws gmail users messages get` with `format=full` to retrieve message details, including `attachments` metadata (IDs and filenames).

2. **Download**: Use `gws gmail users messages attachments get` with the specific `messageId` and `attachmentId`.

3. **Absolute Paths**: Always provide an **absolute path** for the output argument (e.g., `/Users/username/Downloads/file.pdf`). Relative paths will be rejected for security.

### Composing on Behalf of the User

When drafting or replying to email on the user's behalf, apply these three constraints without exception:

- **Async CTAs only** — Never offer calls, meetings, voice/video contact, or any form of synchronous communication. The agent cannot participate in real-time conversations. Use async alternatives instead: "happy to share more over email", "feel free to reply with questions", or leave the closing open with no CTA. Phrases like "let's jump on a call", "schedule a meeting", or "give us a ring" are prohibited.

- **Draft-first rule** — All outbound composition must produce a draft (`gws gmail users drafts create`, or `mcp__claude_ai_Gmail__create_draft`). Never call a send tool without an explicit user instruction to send. This is stricter than the general write-operation safety rule: even if the user says "write a reply", the result is a draft that the user reviews and sends manually.

- **Honest representation** — When composing outreach about the user's product or service, represent it accurately. If the product or operation is automated or AI-assisted, say so rather than implying a human-run team. Do not overclaim capabilities, team size, or operational structure. Inaccurate representation damages trust and creates expectations that cannot be met.

## 📄 Docs, Sheets, and Slides

### Format Selection (Sheets)

Choose output format based on use case:

- **text**: Human-readable, good for quick review

- **csv**: Data export, analysis in other tools

- **json**: Programmatic processing, structured data

### Content Handling

- Docs/Sheets/Slides tools accept URLs directly - no ID extraction needed

- Use markdown for initial document creation when appropriate

- Preserve formatting when reading/modifying content

## 🚫 Common Pitfalls to Avoid

### Don't Do This:

- ❌ Manually extract IDs from URLs when tools accept URLs directly

- ❌ Assume timezone without checking

- ❌ Execute writes without preview and confirmation

- ❌ Create files unless explicitly requested

- ❌ Duplicate parameter documentation from tool descriptions

- ❌ Use relative paths for file downloads (e.g., `downloads/file.txt`)

### Do This Instead:

- ✅ Pass URLs directly to tools that accept them

- ✅ Get user timezone at session start

- ✅ Preview all changes and wait for approval

- ✅ Only create what's requested

- ✅ Focus on behavioral guidance and best practices

- ✅ Always use **absolute paths** for file downloads (e.g., `/Users/me/Downloads/file.txt`)

## 🔍 Error Handling Patterns

### Authentication Errors

- If any tool returns `{"error":"invalid_request"}` or a `gws` call fails with an auth error, it likely indicates an expired or invalid session.

- **Action:** For `gws`, re-run the one-time human OAuth step (`gws auth setup` / `gws auth login`); for MCP, reset credentials and force a re-login. If the tool stays unauthenticated, **fall through to the next tier** in the Tool Selection ladder rather than stalling.

- Inform the user that you are resetting authentication due to an error.

### Graceful Degradation

- If a folder doesn't exist, offer to create it

- If search returns no results, suggest alternatives

- If permissions are insufficient, explain clearly

### Validation Before Action

- Verify file/folder existence before moving

- Check calendar availability before scheduling

- Validate email addresses before sending

## ⚡ Performance Optimization

### Batch Operations

- Group related API calls when possible

- Use field masks to request only needed data

- Implement pagination for large datasets

### Caching Strategy

- Reuse user context throughout session

- Cache frequently accessed metadata

- Minimize redundant API calls

## 📝 Session Management

### Beginning of Session

1. Get user profile (see User Context First — `gws people people get` with `resourceName=people/me`)

2. Establish the user's timezone

3. Establish any relevant context

### During Interaction

- Maintain context awareness

- Apply user preferences consistently

- Handle follow-up questions efficiently

### End of Session

- Confirm all requested tasks completed

- Provide summary if multiple operations performed

- Ensure no pending confirmations

## 🎨 Service-Specific Nuances

### Google Docs

- Support for markdown content creation

- Automatic HTML conversion from markdown

- Position-based text insertion (index 1 for beginning)

### Google Sheets

- Multiple output formats available

- Range-based operations with A1 notation

- Metadata includes sheet structure information

### Google Calendar

- Event creation requires both start and end times

- Support for attendee management

- Response status filtering available

### Gmail

- Full threading support

- Label-based organization

- Draft creation and management

### Google Chat

- Space vs. DM distinction

- Thread-aware messaging

- Unread message filtering

Remember: This guide focuses on **how to think** about using these tools effectively. For specific parameter details, refer to the tool descriptions themselves.