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:

$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 - Create project, enable Docs API
2. Google OAuth Setup Guide - Configure credentials

Quick Start

1. Create ~/.config/agent-skills/google.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.

Commands

See permissions.md for read/write classification of each command.

check

Verify configuration and connectivity.

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

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

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

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

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

Options:

• --title - Document title (required)

Example:

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

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

Arguments:

• document_id - The Google Docs document ID

Example:

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

$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:

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

$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
• --json - Output as JSON

Examples:

# 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

Note: Requires the markdown Python library (pip install --user markdown) and the drive.file scope.

content append

Append text to the end of a document.

$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:

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

$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:

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

$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:

# Delete characters 10-50
$SKILL_DIR/scripts/google-docs.py content delete 1abc...xyz --start-index 10 --end-index 50

# Output:
# ✓ Content deleted successfully

Warning: Be careful with indices. Deleting the wrong range can corrupt document structure.

content insert-after-anchor

Insert markdown-formatted content after a structural anchor (horizontal rule, heading, or bookmark) in a document. Handles text insertion, heading styles, bullet lists, bold formatting, and links in a single operation.

$SKILL_DIR/scripts/google-docs.py content insert-after-anchor DOCUMENT_ID \
  --anchor-type ANCHOR_TYPE --markdown "MARKDOWN_CONTENT"

Arguments:

• document_id - The Google Docs document ID

Options:

• --anchor-type - Type of anchor to find: horizontal_rule, heading, or bookmark (required)
• --anchor-value - Anchor-specific value: heading text (for heading), bookmark ID (for bookmark), or occurrence number (for horizontal_rule, default 1)
• --markdown - Markdown-formatted content to insert (required). Use \n for newlines.

Supported markdown:

Syntax	Result
## Heading	Heading (levels 1-6)
**text**	Bold text
[text](url)	Hyperlink
- item	Bullet list
- item	Nested bullet (indent 2 spaces per level)

Examples:

# Insert after the first horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type horizontal_rule \
  --markdown '## Status Update\n\n**Summary:**\n- Task completed\n  - Sub-task done\n- [Details](https://example.com)'

# Insert after a specific heading
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type heading \
  --anchor-value "Notes" \
  --markdown '- New note item\n- Another item'

# Insert after the second horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type horizontal_rule \
  --anchor-value 2 \
  --markdown '## New Section\n\nParagraph text here.'

formatting apply

Apply text formatting to a range of text.

$SKILL_DIR/scripts/google-docs.py formatting apply DOCUMENT_ID \
  --start-index 1 --end-index 20 --bold --italic

Arguments:

• document_id - The Google Docs document ID

Options:

• --start-index - Start position, inclusive (required)
• --end-index - End position, exclusive (required)
• --bold - Apply bold formatting
• --italic - Apply italic formatting
• --underline - Apply underline formatting
• --font-size SIZE - Set font size in points

Example:

# Make title bold and larger
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 1 --end-index 20 --bold --font-size 18

# Apply italic to a section
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 50 --end-index 100 --italic

# Output:
# ✓ Formatting applied successfully

Examples

Create and populate a document

# Create a new document
$SKILL