google-docs

What this skill does

# Google Docs

Interact with Google Docs for document creation, editing, and content management.

## Installation

**Dependencies**: `pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml markdown`

## Setup Verification

After installation, verify the skill is properly configured:

```bash
$SKILL_DIR/scripts/google-docs.py check
```

This will check:
- Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml, markdown)
- Authentication configuration
- Connectivity to Google Docs API

If anything is missing, the check command will provide setup instructions.

## Authentication

Google Docs uses OAuth 2.0 for authentication. For complete setup instructions, see:

1. [GCP Project Setup Guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/gcp-project-setup.md) - Create project, enable Docs API
2. [Google OAuth Setup Guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/google-oauth-setup.md) - Configure credentials

### Quick Start

1. Create `~/.config/agent-skills/google.yaml`:
   ```yaml
   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   ```

2. Run `$SKILL_DIR/scripts/google-docs.py check` to trigger OAuth flow and verify setup.

On scope or authentication errors, see the [OAuth troubleshooting guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/google-oauth-setup.md#troubleshooting).

## Commands

See [permissions.md](references/permissions.md) for read/write classification of each command.

### check

Verify configuration and connectivity.

```bash
$SKILL_DIR/scripts/google-docs.py check
```

This validates:
- Python dependencies are installed
- Authentication is configured
- Can connect to Google Docs API
- Creates a test document to verify write access

### auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

```bash
$SKILL_DIR/scripts/google-docs.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET
```

Credentials are saved to `~/.config/agent-skills/google-docs.yaml`.

**Options:**
- `--client-id` - OAuth 2.0 client ID (required)
- `--client-secret` - OAuth 2.0 client secret (required)

### auth reset

Clear stored OAuth token. The next command that needs authentication will trigger re-authentication automatically.

```bash
$SKILL_DIR/scripts/google-docs.py auth reset
```

Use this when you encounter scope or authentication errors.

### auth status

Show current OAuth token information without making API calls.

```bash
$SKILL_DIR/scripts/google-docs.py auth status
```

Displays: whether a token is stored, granted scopes, refresh token presence, token expiry, and client ID.

### documents create

Create a new blank Google Doc.

```bash
$SKILL_DIR/scripts/google-docs.py documents create --title "My Document"
```

**Options:**
- `--title` - Document title (required)

**Example:**
```bash
# Create a new document
$SKILL_DIR/scripts/google-docs.py documents create --title "Project Notes"

# Output:
# ✓ Document created successfully
#   Title: Project Notes
#   Document ID: 1abc...xyz
#   URL: https://docs.google.com/document/d/1abc...xyz/edit
```

### documents get

Get document metadata and structure.

```bash
$SKILL_DIR/scripts/google-docs.py documents get DOCUMENT_ID
```

**Arguments:**
- `document_id` - The Google Docs document ID

**Example:**
```bash
# Get document metadata
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz

# Output:
# Title: Project Notes
# Document ID: 1abc...xyz
# Characters: 1234
# Revision ID: abc123
```

### documents read

Read document content as plain text, markdown, or PDF.

```bash
$SKILL_DIR/scripts/google-docs.py documents read DOCUMENT_ID
```

**Arguments:**
- `document_id` - The Google Docs document ID

**Options:**
- `--format` - Output format: `markdown` (default, preserves tables and headings) or `pdf`
- `--output`, `-o` - Output file path (used with pdf format)

**Example:**
```bash
# Read as markdown (default, preserves tables and headings)
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz

# Export as PDF
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz --format pdf --output document.pdf

# Output as markdown:
# # Heading
#
# This is a paragraph.
#
# | Column 1 | Column 2 |
# |----------|----------|
# | Value 1  | Value 2  |
```

**Note:** Markdown and PDF export use Google's native Drive API export. Markdown preserves tables, headings, formatting, and structure with high fidelity. Both require the `drive.readonly` scope.

### documents import

Import a local markdown file as a natively formatted Google Doc. Uses Drive API HTML-to-Docs conversion for full markdown fidelity including tables, code blocks, headings, bold, italic, links, and lists.

```bash
$SKILL_DIR/scripts/google-docs.py documents import FILE_PATH [--title TITLE] [--document-id DOC_ID] [--folder-id ID]
```

**Arguments:**
- `file_path` - Local path to a markdown file

**Options:**
- `--title` - Document title (default: first H1 heading, or filename)
- `--document-id` - Existing document ID to update (replaces content)
- `--folder-id` - Parent folder ID for new documents
- `--no-format` - Skip post-import formatting
- `--json` - Output as JSON

**Examples:**
```bash
# Import a markdown file as a new Google Doc
$SKILL_DIR/scripts/google-docs.py documents import ./report.md --title "Monthly Report"

# Import using the first H1 heading as the title
$SKILL_DIR/scripts/google-docs.py documents import ./notes.md

# Update an existing document with new markdown content
$SKILL_DIR/scripts/google-docs.py documents import ./updated.md --document-id 1abc...xyz

# Import without post-import formatting
$SKILL_DIR/scripts/google-docs.py documents import ./raw.md --no-format
```

**Post-import formatting:** By default, the import applies 1.15x line spacing and 8pt space below paragraphs to the Normal text style. These can be overridden via frontmatter:

```yaml
---
title: My Document
line_spacing: 130
space_below: 10
---
```

After formatting, a readability summary is printed showing heading, paragraph, and list item counts.

**Note:** Requires `markdown`, `mdx-breakless-lists` Python libraries and the `drive.file` + `documents` scopes.

**See also:** For uploading files to Google Drive (non-markdown), sharing, organizing into folders, or exporting documents, use the **google-drive** skill.

### content append

Append text to the end of a document.

```bash
$SKILL_DIR/scripts/google-docs.py content append DOCUMENT_ID --text "Additional content"
```

**Arguments:**
- `document_id` - The Google Docs document ID

**Options:**
- `--text` - Text to append (required)

**Example:**
```bash
# Append text
$SKILL_DIR/scripts/google-docs.py content append 1abc...xyz --text "Meeting notes from today..."

# Output:
# ✓ Text appended successfully
```

### content insert

Insert text at a specific position in the document.

```bash
$SKILL_DIR/scripts/google-docs.py content insert DOCUMENT_ID --text "Insert this" --index 10
```

**Arguments:**
- `document_id` - The Google Docs document ID

**Options:**
- `--text` - Text to insert (required)
- `--index` - Position to insert at, 0-based (required)

**Example:**
```bash
# Insert text at the beginning (index 1, after title)
$SKILL_DIR/scripts/google-docs.py content insert 1abc...xyz --text "Introduction\n\n" --index 1

# Output:
# ✓ Text inserted successfully
```

**Note:** Index 0 is before the document content. Index 1 is at the beginning of content.

### content delete

Delete a range of content from the document.

```bash
$SKILL_DIR/scripts/google-docs.py content delete DOCUMENT_ID --start-index 10 --end-index 50
```

**Arguments:**
- `document_id` - The Google Docs document ID

**Options:**
- `--start-index` - Start position, inclusive (required)
- `--end-index` - End position, exclusive (required)

**Example:**
```bash
# Delete characters 10-50
$SKILL_DIR/scri