Google Docs & Drive Management Skill

Purpose

Manage Google Docs documents and Google Drive files with comprehensive operations:

Google Docs:

• Read document content and structure
• Insert and append text
• Find and replace text
• Basic text formatting (bold, italic, underline)
• Insert page breaks
• Create new documents
• Delete content ranges
• Get document structure (headings)
• Insert inline images from URLs

Google Drive:

• Upload files to Drive
• Download files from Drive
• Search and list files
• Share files with users or publicly
• Create folders
• Move, copy, and delete files
• Get file metadata

Integration: The drive_manager.rb script shares OAuth credentials with docs_manager.rb

📚 Additional Resources:

• See references/large-document-patterns.md for inserting large formatted markdown into existing/template docs
• See references/integration-patterns.md for complete workflow examples
• See references/troubleshooting.md for error handling, debugging, Ruby version, and token format issues
• See references/cli-patterns.md for CLI interface design rationale

When to Use This Skill

Use this skill when:

• User requests to read or view a Google Doc
• User wants to create a new document
• User wants to edit document content
• User requests text formatting or modifications
• User asks about document structure or headings
• User wants to find and replace text
• User needs to insert a large markdown file into an existing/template Google Doc
• User wants to insert local images into a Google Doc (via Drive upload)
• Keywords: "Google Doc", "document", "edit doc", "format text", "insert text", "insert markdown"

⚠️ Large Document Insertion: For markdown files >5KB or documents with many tables, use scripts/insert_markdown_to_doc.rb instead of docs_manager.rb insert-from-markdown. It handles rate limiting, batching, real table insertion, and code font formatting. See references/large-document-patterns.md.

📋 Discovering Your Documents: To list or search for documents, use drive_manager.rb:

# List recent documents
scripts/drive_manager.rb search \
  --query "mimeType='application/vnd.google-apps.document'" \
  --max-results 50

# Search by name
scripts/drive_manager.rb search \
  --query "name contains 'Report' and mimeType='application/vnd.google-apps.document'"

Core Workflows

1. Read Document

Read full document content:

scripts/docs_manager.rb read <document_id>

Get document structure (headings):

scripts/docs_manager.rb structure <document_id>

Output:

• Full text content with paragraphs
• Document metadata (title, revision ID)
• Heading structure with levels and positions

2. Create Documents

Create new document (plain text):

echo '{
  "title": "Project Proposal",
  "content": "Initial plain text content..."
}' | scripts/docs_manager.rb create

Create document from Markdown (RECOMMENDED):

echo '{
  "title": "Project Proposal",
  "markdown": "# Project Proposal\n\n## Overview\n\nThis is **bold** and *italic* text.\n\n- Bullet point 1\n- Bullet point 2\n\n| Column 1 | Column 2 |\n|----------|----------|\n| Data 1   | Data 2   |"
}' | scripts/docs_manager.rb create-from-markdown

Supported Markdown Features:

• Headings: #, ##, ###, #### → Google Docs HEADING_1 through HEADING_4
• Bold: **text**
• Italic: *text*
• Code: `text` → Consolas font (docs_manager uses Courier New; insert_markdown_to_doc uses Consolas)
• Code blocks: ``` → Consolas font (only in insert_markdown_to_doc.rb)
• Bullet lists: - item or * item
• Numbered lists: 1. item
• Checkboxes: - [ ] unchecked and - [x] checked
• Horizontal rules: ---
• Tables: | col1 | col2 | (with separator row, bold header in insert_markdown_to_doc.rb)
• Images: ![alt](path) → uploaded to Drive and inserted inline (only in insert_markdown_to_doc.rb with --insert-images)

Document ID:

• Returned in response for future operations
• Use with drive_manager.rb for sharing/organizing

3. Insert and Append Text

Insert plain text at specific position:

echo '{
  "document_id": "abc123",
  "text": "This text will be inserted at the beginning.\n\n",
  "index": 1
}' | scripts/docs_manager.rb insert

Insert formatted Markdown (RECOMMENDED):

echo '{
  "document_id": "abc123",
  "markdown": "## New Section\n\nThis has **bold** and *italic* formatting.\n\n- Item 1\n- Item 2",
  "index": 1
}' | scripts/docs_manager.rb insert-from-markdown

Append text to end of document:

echo '{
  "document_id": "abc123",
  "text": "\n\nThis text will be appended to the end."
}' | scripts/docs_manager.rb append

Index Positions:

• Document starts at index 1
• Use read command to see current content
• Use structure command to find heading positions
• End of document: use append instead of calculating index
• For insert-from-markdown, omit index to append at end

4. Find and Replace

Simple find and replace:

echo '{
  "document_id": "abc123",
  "find": "old text",
  "replace": "new text"
}' | scripts/docs_manager.rb replace

Case-sensitive replacement:

echo '{
  "document_id": "abc123",
  "find": "IMPORTANT",
  "replace": "CRITICAL",
  "match_case": true
}' | scripts/docs_manager.rb replace

Replace all occurrences:

• Automatically replaces all matches
• Returns count of replacements made
• Use for bulk text updates

5. Text Formatting

Format text range (bold):

echo '{
  "document_id": "abc123",
  "start_index": 1,
  "end_index": 20,
  "bold": true
}' | scripts/docs_manager.rb format

Multiple formatting options:

echo '{
  "document_id": "abc123",
  "start_index": 50,
  "end_index": 100,
  "bold": true,
  "italic": true,
  "underline": true
}' | scripts/docs_manager.rb format

Formatting Options:

• bold: true/false
• italic: true/false
• underline: true/false
• All options are independent and can be combined

6. Page Breaks

Insert page break:

echo '{
  "document_id": "abc123",
  "index": 500
}' | scripts/docs_manager.rb page-break

Use Cases:

• Separate document sections
• Start new content on fresh page
• Organize long documents

7. Delete Content

Delete text range:

echo '{
  "document_id": "abc123",
  "start_index": 100,
  "end_index": 200
}' | scripts/docs_manager.rb delete

Clear entire document:

# Read document first to get end index
scripts/docs_manager.rb read abc123

# Then delete all content (start at 1, end at last index - 1)
echo '{
  "document_id": "abc123",
  "start_index": 1,
  "end_index": 500
}' | scripts/docs_manager.rb delete

8. Insert Images

Insert image from URL:

echo '{
  "document_id": "abc123",
  "image_url": "https://storage.googleapis.com/bucket/image.png"
}' | scripts/docs_manager.rb insert-image

Insert image with specific size:

echo '{
  "document_id": "abc123",
  "image_url": "https://storage.googleapis.com/bucket/image.png",
  "width": 400,
  "height": 300
}' | scripts/docs_manager.rb insert-image

Insert image at specific position:

echo '{
  "document_id": "abc123",
  "image_url": "https://storage.googleapis.com/bucket/image.png",
  "index": 100
}' | scripts/docs_manager.rb insert-image

Image URL Requirements:

• URL must be publicly accessible (Google Docs fetches the image)
• Supported formats: PNG, JPEG, GIF
• SVG is NOT supported - convert to PNG first
• For private/local images: upload to Drive first, share publicly, then use the Drive URL
• Use insert_markdown_to_doc.rb --insert-images to automate this workflow for local images referenced in markdown

Sizing Tips:

• To fit page width with default margins: use width: 468 (points)
• Specifying only width will auto-scale height proportionally
• Specifying only height will auto-scale width proportionally
• 1 inch = 72 points

9. Insert Tables

Insert empty table:

echo '{
  "document_id": "abc123",
  "rows": 3,
  "cols": 4
}' | scripts/docs_manager.rb insert-table

Insert table with data:

echo '{
  "document_id": "abc123",
  "rows": 3,
  "cols": 2,
  "data": [
    ["Header 1", "Header 2"],
    ["Row 1 Col 1", "Row 1 Col 2"],
    ["Row 2 Col 1", "Row 2 Col 2"]
  ]
}' | scripts/docs_manager.rb insert-table

Insert table at specific position:

echo '{
  "document_id": "abc123",
  "rows": 2,
  "cols": 3,
  "index": 100,
  "data": [["A", "B", "C"], ["1", "2", "3"]]
}' | scripts/docs_manager.rb insert-table

Note: Tables can also be created via Markdown in create-from-markdown:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

10. Large Document Insertion (insert_markdown_to_doc.rb)

Use this instead of insert-from-markdown for documents over ~5KB, or any document with many tables/code blocks.

Insert markdown into an existing template doc (preserving cover page):

scripts/insert_markdown_to_doc.rb \
  --clear-after 1234 \
  --code-font Consolas \
  --insert-images \
  --image-base-dir ./docs \
  <document_id> ./docs/my_document.md

Insert markdown into an empty doc:

scripts/insert_markdown_to_doc.rb <document_id> ./content.md

Key Features:

• Batched API calls (1 insert + 1 format per segment) to avoid rate limits
• Real Google Docs tables with bold headers
• Code blocks and inline code in Consolas font (configurable)
• H1-H4 heading support
• Automatic mermaid diagram → placeholder conversion
• Local image upload to Drive + inline insertion
• Chunking for documents over 20KB
• Rate limit recovery with sleep between batches

See references/large-document-patterns.md for detailed strategy, error recovery, and chunking guide.

Natural Language Examples

User Says: "Read the content of this Google Doc: abc123"

scripts/docs_manager.rb read abc123

User Says: "Create a new document called 'Meeting Notes' with the text 'Attendees: John, Sarah'"

echo '{
  "title": "Meeting Notes",
  "content": "Attendees: John, Sarah"
}' | scripts/docs_manager.rb create

User Says: "Add 'Next Steps' section to the end of document abc123"

echo '{
  "document_id": "abc123",
  "text": "\n\n## Next Steps\n\n- Review proposals\n- Schedule follow-up"
}' | scripts/docs_manager.rb append

User Says: "Replace all instances of 'Q3' with 'Q4' in document abc123"

echo '{
  "document_id": "abc123",
  "find": "Q3",
  "replace": "Q4"
}' | scripts/docs_manager.rb replace

User Says: "Make the first 50 characters of document abc123 bold"

echo '{
  "document_id": "abc123",
  "start_index": 1,
  "end_index": 50,
  "bold": true
}' | scripts/docs_manager.rb format

Understanding Document Index Positions

Index System:

• Documents use zero-based indexing with offset
• Index 1 = start of document (after title)
• Each character (including spaces and newlines) has an index
• Use read to see current content and plan insertions
• Use structure to find heading positions

Finding Positions:

1. Read document to see content
2. Count characters to desired position
3. Or use heading structure for section starts
4. Remember: index 1 = very beginning

Example:

"Hello World\n\nSecond paragraph"

Index 1: "H" (start)
Index 11: "\n" (first newline)
Index 13: "S" (start of "Second")
Index 29: end of document

Google Drive Operations

The drive_manager.rb script provides comprehensive Google Drive file management.

Upload Files

# Upload a file to Drive root
scripts/drive_manager.rb upload --file ./document.pdf

# Upload to specific folder
scripts/drive_manager.rb upload --file ./diagram.excalidraw --folder-id abc123

# Upload with custom name
scripts/drive_manager.rb upload --file ./local.txt --name "Remote Name.txt"

Download Files

# Download a file
scripts/drive_manager.rb download --file-id abc123 --output ./local_copy.pdf

# Export Google Doc as PDF
scripts/drive_manager.rb download --file-id abc123 --output ./doc.pdf --export-as pdf

# Export Google Sheet as CSV
scripts/drive_manager.rb download --file-id abc123 --output ./data.csv --export-as csv

Search and List Files

# List recent files
scripts/drive_manager.rb list --max-results 20

# Search by name
scripts/drive_manager.rb search --query "name contains 'Report'"

# Search by type
scripts/drive_manager.rb search --query "mimeType='application/vnd.google-apps.document'"

# Search in folder
scripts/drive_manager.rb search --query "'folder_id' in parents"

# Combine queries
scripts/drive_manager.rb search --query "name contains '.excalidraw' and modifiedTime > '2024-01-01'"

Share Files

# Share with specific user (reader)
scripts/drive_manager.rb share --file-id abc123 --email user@example.com --role reader

# Share with write access
scripts/drive_manager.rb share --file-id abc123 --email user@example.com --role writer

# Make publicly accessible (anyone with link)
scripts/drive_manager.rb share --file-id abc123 --type anyone --role reader

# Share with entire domain
scripts/drive_manager.rb share --file-id abc123 --type domain --domain example.com --role reader

Folder Management

# Create a folder
scripts/drive_manager.rb create-folder --name "Project Documents"

# Create folder inside another folder
scripts/drive_manager.rb create-folder --name "Diagrams" --parent-id abc123

# Move file to folder
scripts/drive_manager.rb move --file-id file123 --folder-id folder456

Other Operations

# Get file metadata
scripts/drive_manager.rb get-metadata --file-id abc123

# Copy a file
scripts/drive_manager.rb copy --file-id abc123 --name "Copy of Document"

# Update file content (replace)
scripts/drive_manager.rb update --file-id abc123 --file ./new_content.pdf

# Delete file (moves to trash)
scripts/drive_manager.rb delete --file-id abc123

Output Format

All commands return JSON with consistent structure:

{
  "status": "success",
  "operation": "upload",
  "file": {
    "id": "1abc...",
    "name": "document.pdf",
    "mime_type": "application/pdf",
    "web_view_link": "https://drive.google.com/file/d/1abc.../view",
    "web_content_link": "https://drive.google.com/uc?id=1abc...",
    "created_time": "2024-01-15T10:30:00Z",
    "modified_time": "2024-01-15T10:30:00Z",
    "size": 12345
  }
}

---

Integration Workflows

Create and Organize Documents

# Step 1: Create document (returns document_id)
echo '{"title":"Report"}' | scripts/docs_manager.rb create
# Returns: {"document_id": "abc123"}

# Step 2: Add content
echo '{"document_id":"abc123","text":"# Report\n\nContent here"}' | scripts/docs_manager.rb insert

# Step 3: Organize in folder
scripts/drive_manager.rb move --file-id abc123 --folder-id [folder_id]

# Step 4: Share with team
scripts/drive_manager.rb share --file-id abc123 --email team@company.com --role writer

Export Document to PDF

scripts/drive_manager.rb download --file-id abc123 --output ./report.pdf --export-as pdf

Excalidraw Diagrams Workflow

For creating and managing Excalidraw diagrams, see the excalidraw-diagrams skill which integrates with drive_manager.rb for:

• Uploading .excalidraw files to Drive
• Getting shareable edit URLs for Excalidraw web
• Round-trip editing between AI and human

Authentication Setup

Shared with Other Google Skills:

• Uses same OAuth credentials and token
• Located at: ~/.claude/.google/client_secret.json and ~/.claude/.google/token.json
• Shares token with email, calendar, contacts, drive, and sheets skills
• Requires Documents, Drive, Sheets, Calendar, Contacts, and Gmail API scopes

First Time Setup:

1. Run any docs operation
2. Script will prompt for authorization URL
3. Visit URL and authorize all Google services
4. Enter authorization code when prompted
5. Token stored for all Google skills

Re-authorization:

• Token automatically refreshes when expired
• If refresh fails, re-run authorization flow
• All Google skills will work after single re-auth

Bundled Resources

Scripts

scripts/docs_manager.rb

• Comprehensive Google Docs API wrapper
• All document operations: read, create, insert, append, replace, format, delete
• Document structure analysis (headings)
• Automatic token refresh
• Shared OAuth with other Google skills

Operations:

• read: View document content
• structure: Get document headings and structure
• insert: Insert plain text at specific index
• insert-from-markdown: Insert formatted markdown content
• append: Append text to end
• replace: Find and replace text
• format: Apply text formatting (bold, italic, underline)
• page-break: Insert page break
• create: Create new document (plain text)
• create-from-markdown: Create document with formatted markdown
• delete: Delete content range
• insert-image: Insert inline image from URL
• insert-table: Insert table with optional data

Output Format:

• JSON with status: 'success' or status: 'error'
• Document operations return document_id and revision_id
• See script help: scripts/docs_manager.rb --help

⚠️ Limitation: insert-from-markdown works for small content but has formatting index offset bugs on large documents or documents with existing content. Use insert_markdown_to_doc.rb for large docs.

scripts/insert_markdown_to_doc.rb

• Large document insertion with rate limiting and batching
• Handles documents 100KB+ with many tables and code blocks
• Real Google Docs tables with bold headers (not pipe-separated text)
• Code blocks and inline code in Consolas font (configurable via --code-font)
• H1-H4 heading support
• Mermaid diagram preprocessing (replaced with placeholders)
• Local image upload to Drive + inline insertion (--insert-images)
• Template document support (--clear-after INDEX preserves cover page)
• Auto-chunking to stay under API rate limits

Usage: scripts/insert_markdown_to_doc.rb [options] <document_id> <markdown_file>

Options: --code-font, --start-index, --clear-after, --insert-images, --image-base-dir, --chunk-size

See references/large-document-patterns.md for full documentation.

References

references/large-document-patterns.md

• Battle-tested patterns for large markdown insertion
• Chunking, batching, and rate limiting strategy
• Template document preservation
• Image insertion via Drive workflow
• Table insertion details and error recovery

references/docs_operations.md

• Complete operation reference
• Parameter documentation
• Index position examples
• Common workflows

references/formatting_guide.md

• Text formatting options
• Style guidelines
• Document structure best practices
• Heading hierarchy

Examples

examples/sample_operations.md

• Common document operations
• Workflow examples
• Index calculation examples
• Integration with drive_manager.rb for file operations

Error Handling

Authentication Error:

{
  "status": "error",
  "code": "AUTH_ERROR",
  "message": "Token refresh failed: ..."
}

Action: Guide user through re-authorization

Document Not Found:

{
  "status": "error",
  "code": "API_ERROR",
  "message": "Document not found"
}

Action: Verify document ID, check permissions

Invalid Index:

{
  "status": "error",
  "code": "API_ERROR",
  "message": "Invalid index position"
}

Action: Read document to verify current length, adjust index

API Error:

{
  "status": "error",
  "code": "API_ERROR",
  "message": "Failed to update document: ..."
}

Action: Display error to user, suggest troubleshooting steps

Best Practices

Document Creation

1. Always provide meaningful title
2. Add initial content when creating for better context
3. Save returned document_id for future operations
4. Use drive_manager.rb to organize and share

Text Insertion

1. Read document first to understand current structure
2. Use structure command to find heading positions
3. Index 1 = start of document
4. Use append for adding to end (simpler than calculating index)
5. Include newlines (\n) for proper formatting

Find and Replace

1. Test pattern match first on small section
2. Use case-sensitive matching for precise replacements
3. Returns count of replacements made
4. Cannot undo - consider reading document first for backup

Text Formatting

1. Calculate index positions carefully
2. Read document to verify text location
3. Can combine bold, italic, underline
4. Formatting applies to exact character range

Document Structure

1. Use heading structure for navigation
2. Insert page breaks between major sections
3. Maintain consistent formatting throughout
4. Use structure command to validate hierarchy

Quick Reference

Read document:

scripts/docs_manager.rb read <document_id>

Create document from Markdown (RECOMMENDED):

echo '{"title":"My Doc","markdown":"# Heading\n\nParagraph with **bold**."}' | scripts/docs_manager.rb create-from-markdown

Create document (plain text):

echo '{"title":"My Doc","content":"Initial text"}' | scripts/docs_manager.rb create

Insert formatted Markdown:

echo '{"document_id":"abc123","markdown":"## Section\n\n- Item 1\n- Item 2"}' | scripts/docs_manager.rb insert-from-markdown

Insert plain text at beginning:

echo '{"document_id":"abc123","text":"New text","index":1}' | scripts/docs_manager.rb insert

Append to end:

echo '{"document_id":"abc123","text":"Appended text"}' | scripts/docs_manager.rb append

Find and replace:

echo '{"document_id":"abc123","find":"old","replace":"new"}' | scripts/docs_manager.rb replace

Format text:

echo '{"document_id":"abc123","start_index":1,"end_index":50,"bold":true}' | scripts/docs_manager.rb format

Get document structure:

scripts/docs_manager.rb structure <document_id>

Insert table:

echo '{"document_id":"abc123","rows":3,"cols":2,"data":[["A","B"],["1","2"],["3","4"]]}' | scripts/docs_manager.rb insert-table

Insert image from URL:

echo '{"document_id":"abc123","image_url":"https://example.com/image.png"}' | scripts/docs_manager.rb insert-image

Insert large markdown into template doc (RECOMMENDED for large docs):

scripts/insert_markdown_to_doc.rb --clear-after 1234 --insert-images --image-base-dir ./docs abc123 ./docs/content.md

Example Workflow: Creating and Editing a Report

1. Create document with formatted content:

   echo '{
     "title": "Q4 Report",
     "markdown": "# Q4 Report\n\n## Executive Summary\n\nRevenue increased **25%** over Q3 targets.\n\n## Key Metrics\n\n| Metric | Q3 | Q4 |\n|--------|-----|-----|\n| Revenue | $1M | $1.25M |\n| Users | 10K | 15K |\n\n## Next Steps\n\n- [ ] Finalize budget\n- [ ] Schedule review meeting\n- [x] Complete analysis"
   }' | scripts/docs_manager.rb create-from-markdown
   # Returns: {"document_id": "abc123"}
   

2. Add more content later:

   echo '{
     "document_id": "abc123",
     "markdown": "\n\n## Appendix\n\nAdditional *details* and **notes** here."
   }' | scripts/docs_manager.rb insert-from-markdown
   

3. Replace text if needed:

   echo '{
     "document_id": "abc123",
     "find": "Q3",
     "replace": "Q4"
   }' | scripts/docs_manager.rb replace
   

4. Share with team:

   scripts/drive_manager.rb share --file-id abc123 --email team@company.com --role writer
   

Version History

• 1.3.0 (2026-02-18) - Added insert_markdown_to_doc.rb for large document insertion with rate limiting, batching, real tables, code font (Consolas), H4 headings, mermaid preprocessing, local image upload via Drive, and template doc support. Added references/large-document-patterns.md. Updated troubleshooting with Ruby version, token YAML format, and Drive API enablement issues.
• 1.2.0 (2025-12-25) - Added markdown support documentation: create-from-markdown, insert-from-markdown, insert-table commands. Supports headings, bold, italic, code, lists, checkboxes, tables, and horizontal rules.
• 1.1.0 (2025-12-20) - Added Google Drive operations via drive_manager.rb: upload, download, search, list, share, move, copy, delete, folder management. Integrated with excalidraw-diagrams skill for diagram workflows.
• 1.0.0 (2025-11-10) - Initial Google Docs skill with full document operations: read, create, insert, append, replace, format, page breaks, structure analysis. Shared OAuth token with email, calendar, contacts, drive, and sheets skills.

---

Dependencies: Ruby (3.0+ via Homebrew recommended) with google-apis-docs_v1, google-apis-drive_v3, googleauth gems (shared with other Google skills). System Ruby (macOS 2.6) is too old — use /opt/homebrew/opt/ruby/bin/ruby.