GSuite Skill

Google Suite integration for Claude Code with multi-account support (enterprise + personal).

Capabilities

• •Sheets: Read/write cells, create spreadsheets, append rows, manage sheets (list/add/rename/delete tabs)
• •Docs: Read/write documents, create docs, export to PDF/DOCX, manage tabs (list/create/rename/delete)
• •Slides: Read presentations, create slides, add content
• •Drive: List files, share, manage permissions, create folders
• •Gmail: Read/send/draft messages, search, manage labels
• •Calendar: List/create/update/delete events, manage calendars
• •Tasks: List/create/complete/delete tasks
• •People: Search contacts, resolve names to emails before operations
• •Auth: Multi-account management with account switching

Orchestration

CRITICAL: NEVER execute tools directly. ALWAYS delegate via /spawn.

For delegation patterns and examples, see cookbook/orchestration.md.

Conventions

Tools: All PEP 723 uv scripts in core/skills/gsuite/tools/. All support --help and --account/-a <email>. Verify exact tool names first (ls tools/) - naming is inconsistent (e.g., gcalendar vs docs).

Cookbook: <tool>.py -> cookbook/<tool>.md (MANDATORY read before executing). If cookbook missing, check <tool>.py --help directly.

Customization: <tool>.py -> $AGENTIC_GLOBAL/customization/gsuite/<tool>.md

Large Content Strategy: For multi-line or complex content (e.g.: docs, emails, slides):

1. •Write content to temp file first (e.g., /tmp/content.md)
2. •Pipe/cat file to CLI tool: cat /tmp/content.md | uv run <tool>.py write ...
3. •Benefits: Avoids shell escaping issues, handles large content reliably, easier to debug

Workflow

1. Initialize

• •Get date context: date "+%Y-%m-%dT%H:%M:%S %Z"
• •Check auth: uv run auth.py status --json
• •Resolve account (ask if ambiguous, remember for session)

2. Load Preferences (BLOCKING)

STOP. Check customization BEFORE any tool execution or API search. Check $AGENTIC_GLOBAL/customization/gsuite/ for:

• •index.md (always)
• •<tool>.md (if exists)
• •people.md (if name mentioned)

3. Resolve People (BLOCKING)

NEVER search People API before checking customization. If name (not email) mentioned:

1. •FIRST: Check $AGENTIC_GLOBAL/customization/gsuite/people.md
2. •ONLY IF NOT FOUND: Fall back to People API via cookbook/people.md
3. •Handle ambiguous matches via AskUserQuestion

4. Read Cookbook (BLOCKING)

STOP. Read cookbook before executing any tool.

1. •Verify exact tool name: ls tools/ (e.g., docs.py not gdocs.py)
2. •Check cookbook/<tool>.md (exact match)
3. •If no cookbook: <tool>.py --help

5. Execute & Report

Run tool, report results (status, data, errors).

6. Learn Preferences (Post-Execution)

On user correction -> read cookbook/preferences.md for storage flow.

Anti-Patterns (NEVER DO)

• •NEVER create public assets - All Drive files, Docs, Sheets, Slides must remain private. Never use role: anyone, type: anyone, or public visibility settings unless user explicitly requests AND confirms.
• •Assuming tool names without verifying (ls tools/ first)
• •Searching People API before reading people.md customization
• •Executing tools before reading their cookbook
• •Skipping index.md preferences check

Configuration

Config directory: ~/.agents/gsuite/

~/.agents/gsuite/
  credentials.json          # OAuth client credentials
  service-account.json      # Enterprise service account (optional)
  config.yml                # Confirmation settings (optional)
  active_account            # Current active account
  accounts/<email>/token.json

Confirmation Settings

Write operations require confirmation by default. Configure in config.yml:

confirmation:
  default: true    # Global default
  gmail: true      # Per-tool override
  tasks: false     # Disable for specific tools

Use --yes or -y flag to bypass confirmation.

Extended API Access

For --extra parameter usage (recurring events, CC/BCC, subtasks, etc.), see cookbook/extra.md.

Error Handling

• •No credentials: Read cookbook/auth.md for interactive setup
• •Token expired: Auto-refresh via google-auth library
• •Rate limit (429): Exponential backoff with retry
• •Permission denied: Verify account has access to resource