Agent-Skills.md

Agent Skills: google-docs

Google Docs API for document editing. Use when user mentions "Google

UncategorizedID: vm0-ai/vm0-skills/google-docs

Repository

vm0-ai/vm0-skills
vm0-ai
508

Install this agent skill to your local

pnpm dlx add-skill https://github.com/vm0-ai/vm0-skills/tree/HEAD/google-docs

Skill Files

Browse the full folder contents for google-docs.

Download Skill

Loading file tree…

google-docs/SKILL.md

Skill Metadata

Name
google-docs
Description
Google Docs API for document editing. Use when user mentions "Google

How to Use

Base URL: https://docs.googleapis.com/v1

Finding your Document ID: The document ID is in the URL: https://docs.google.com/document/d/{DOCUMENT_ID}/edit

1. Create New Document

Create a blank document with a title:

Write to /tmp/gdocs_request.json:

{
  "title": "My New Document"
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '{documentId, title, documentUrl: ("https://docs.google.com/document/d/" + .documentId + "/edit")}'

2. Get Document Content

Read the entire document structure and content:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq '{title: .title, body: .body.content}'

3. Get Document Metadata Only

Get just the title and basic properties:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq '{documentId, title, revisionId, suggestionsViewMode}'

4. Insert Text at Beginning

Insert text at the start of the document (index 1):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Hello, this is my first paragraph.\n"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

5. Insert Text at Specific Location

Insert text at a specific index (get indexes from document content):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 25
        },
        "text": "This is inserted text.\n"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

6. Delete Content Range

Delete text from a specific range:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "deleteContentRange": {
        "range": {
          "startIndex": 1,
          "endIndex": 50
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

7. Find and Replace Text

Replace all occurrences of text throughout the document:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "replaceAllText": {
        "containsText": {
          "text": "old text",
          "matchCase": true
        },
        "replaceText": "new text"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies[0].replaceAllText'

8. Format Text as Bold

Make text bold in a specific range:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "updateTextStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 20
        },
        "textStyle": {
          "bold": true
        },
        "fields": "bold"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

9. Format Text with Multiple Styles

Apply multiple text styles (bold, italic, font size, color):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "updateTextStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 30
        },
        "textStyle": {
          "bold": true,
          "italic": true,
          "fontSize": {
            "magnitude": 14,
            "unit": "PT"
          },
          "foregroundColor": {
            "color": {
              "rgbColor": {
                "red": 0.2,
                "green": 0.4,
                "blue": 0.8
              }
            }
          }
        },
        "fields": "bold,italic,fontSize,foregroundColor"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

10. Set Paragraph Alignment

Change paragraph alignment (LEFT, CENTER, RIGHT, JUSTIFIED):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "updateParagraphStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 50
        },
        "paragraphStyle": {
          "alignment": "CENTER"
        },
        "fields": "alignment"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

11. Create Bulleted List

Convert paragraphs to a bulleted list:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "createParagraphBullets": {
        "range": {
          "startIndex": 1,
          "endIndex": 100
        },
        "bulletPreset": "BULLET_DISC_CIRCLE_SQUARE"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

Available bullet presets:

  • BULLET_DISC_CIRCLE_SQUARE
  • BULLET_DIAMONDX_ARROW3D_SQUARE
  • BULLET_CHECKBOX
  • NUMBERED_DECIMAL_ALPHA_ROMAN
  • NUMBERED_DECIMAL_NESTED

12. Insert Table

Insert a table with specified rows and columns:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertTable": {
        "rows": 3,
        "columns": 4,
        "location": {
          "index": 1
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

13. Insert Page Break

Insert a page break at a specific location:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertPageBreak": {
        "location": {
          "index": 50
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

14. Insert Inline Image

Insert an image from a URL:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertInlineImage": {
        "uri": "https://example.com/image.png",
        "location": {
          "index": 1
        },
        "objectSize": {
          "height": {
            "magnitude": 200,
            "unit": "PT"
          },
          "width": {
            "magnitude": 300,
            "unit": "PT"
          }
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

15. Batch Operations (Multiple Updates)

Combine multiple operations in a single request:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Title: Important Document\n\n"
      }
    },
    {
      "updateTextStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 26
        },
        "textStyle": {
          "bold": true,
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        },
        "fields": "bold,fontSize"
      }
    },
    {
      "insertText": {
        "location": {
          "index": 28
        },
        "text": "This is the body text of the document.\n"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // (.replies | length)'

16. Extract Plain Text

Get just the text content from a document:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq -r '.body.content[]?.paragraph?.elements[]?.textRun?.content' | tr -d '\0'

17. Get Document Structure

View document structure with element types and indexes:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq '.body.content[] | {startIndex, endIndex, paragraph: .paragraph.elements[0].textRun.content}'

Common Scopes

| Scope | Permission | |-------|------------| | documents.readonly | Read-only access | | documents | Full read/write access | | drive.readonly | Read files in Drive | | drive.file | Access files created by app | | drive | Full Drive access |

Use full URL: https://www.googleapis.com/auth/documents

Index Reference

Understanding indexes is critical for the Google Docs API:

  • Index 1: Start of document body
  • Index N: Each character, newline, and structural element increments the index
  • End index: Use "endIndex": startIndex + textLength for ranges
  • Tip: Get document content first to see current indexes

Text Style Fields

When using updateTextStyle, specify which fields to update in the fields parameter:

| Field | Description | |-------|-------------| | bold | Bold text | | italic | Italic text | | underline | Underline text | | strikethrough | Strikethrough text | | fontSize | Font size (PT or PX) | | foregroundColor | Text color (RGB) | | backgroundColor | Background color (RGB) | | fontFamily | Font name (e.g., "Arial") | | baselineOffset | Superscript/subscript | | link | Hyperlink URL |

Use comma-separated for multiple: "fields": "bold,italic,fontSize"

Paragraph Style Fields

When using updateParagraphStyle:

| Field | Description | |-------|-------------| | alignment | LEFT, CENTER, RIGHT, JUSTIFIED | | lineSpacing | Line spacing percentage (100 = single) | | direction | LEFT_TO_RIGHT or RIGHT_TO_LEFT | | spaceAbove | Space before paragraph | | spaceBelow | Space after paragraph | | indentFirstLine | First line indentation | | indentStart | Left indentation | | indentEnd | Right indentation | | namedStyleType | HEADING_1, HEADING_2, NORMAL_TEXT, etc. |

Guidelines

  1. Batch operations: Combine multiple requests in a single batchUpdate call to improve performance
  2. Index calculation: Always get current document content to determine correct indexes
  3. Request order: Requests are processed in order; later requests see effects of earlier ones
  4. Fields parameter: Always specify which fields to update to avoid overwriting other properties
  5. RGB colors: Color values range from 0.0 to 1.0 (not 0-255)
  6. Share permissions: Ensure the authenticated user has edit access to the document
  7. batchUpdate responses: Some operations (updateParagraphStyle, insertTable, insertPageBreak, insertInlineImage) return empty or absent .replies; output of "done" means success with no reply data. An .error key indicates failure.

API Reference

  • REST Reference: https://developers.google.com/docs/api/reference/rest
  • Guides: https://developers.google.com/docs/api/how-tos/overview
  • OAuth Playground: https://developers.google.com/oauthplayground/
  • Scopes: https://developers.google.com/identity/protocols/oauth2/scopes#docs
  • Request Types: https://developers.google.com/docs/api/reference/rest/v1/documents/request