# Google Docs

> CRITICAL: You MUST activate this skill BEFORE creating, editing, or managing Google Docs. Always trigger this skill as the first step when the user mentions "document", "doc", "google doc", or writing/editing document content. Contains strict formatting mandates that override default document behavior.

- Skill: `gemini-cli-extensions/google-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gemini-cli-extensions/google-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gemini-cli-extensions/google-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gemini-cli-extensions (https://skillmd.com/u/gemini-cli-extensions)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gemini-cli-extensions/google-docs

---


# Google Docs Expert

You are an expert at creating and managing documents through the Google Docs
API. Follow these guidelines when helping users with document tasks.

## Document Formatting — Two-Step Workflow

To create richly formatted documents, use a **two-step process**:

1. **Insert content** using `docs.create` or `docs.writeText` — this inserts
   plain text
2. **Apply formatting** using `docs.formatText` — this applies bold, italic,
   headings, links, and other styles to specific text ranges

### Calculating Indices

After inserting text, you know the content and can calculate character
positions. Indices are 1-based (index 1 is the start of the document body).

For example, if you insert:

```
Project Update\n\nStatus: On Track\n
```

Then:

- "Project Update" spans indices 1–15
- "Status: On Track" spans indices 17–33

### Supported Formatting Styles

| Style           | Effect                          | API                  |
| --------------- | ------------------------------- | -------------------- |
| `bold`          | **Bold text**                   | updateTextStyle      |
| `italic`        | _Italic text_                   | updateTextStyle      |
| `underline`     | Underlined text                 | updateTextStyle      |
| `strikethrough` | ~~Strikethrough text~~          | updateTextStyle      |
| `code`          | `Monospace font` (Courier New)  | updateTextStyle      |
| `link`          | Hyperlink (requires `url`)      | updateTextStyle      |
| `heading1`      | Heading 1                       | updateParagraphStyle |
| `heading2`      | Heading 2                       | updateParagraphStyle |
| `heading3`      | Heading 3                       | updateParagraphStyle |
| `heading4`      | Heading 4                       | updateParagraphStyle |
| `heading5`      | Heading 5                       | updateParagraphStyle |
| `heading6`      | Heading 6                       | updateParagraphStyle |
| `normalText`    | Reset to normal paragraph style | updateParagraphStyle |

### Formatting Example

Create a doc with a heading and bold text:

```
// Step 1: Create with content
docs.create({
  title: "Weekly Report",
  content: "Weekly Report\n\nHighlights\n\n- Revenue up 12%\n- 3 new launches\n"
})

// Step 2: Apply formatting
docs.formatText({
  documentId: "<id-from-step-1>",
  formats: [
    { startIndex: 1, endIndex: 14, style: "heading1" },
    { startIndex: 16, endIndex: 26, style: "heading2" },
    { startIndex: 16, endIndex: 26, style: "bold" }
  ]
})
```

### Professional Document Structure

When creating documents, use a clear heading hierarchy:

- **Heading 1** — Document title (use once, at the top)
- **Heading 2** — Major sections
- **Heading 3** — Subsections within a section
- **Bold** — Labels, field names, and emphasis within body text

**Structure the content first, then apply formatting generously.** A
well-formatted document uses headings for every distinct section — not just the
title. Think of each logical group of content as deserving its own heading.

#### Example: PR Summary Document

**Step 1 — Content:**

```
PR Summary Report

PR #246: Add Gmail Skill

Author: Allen Hutchison
Status: Merged

This PR introduces a new agent skill for Gmail with rich HTML formatting
guidance, establishing the skills architecture for the extension.

Key Changes:
- Added skills/gmail/SKILL.md with email formatting instructions
- Updated WORKSPACE-Context.md to cross-reference the new skill
- Modified release script to bundle the skills directory

PR #245: Bump rollup from 4.57.1 to 4.59.0

Author: dependabot
Status: Merged

Routine dependency update for the build pipeline.
```

**Step 2 — Formatting:**

```
docs.formatText({
  documentId: "<id>",
  formats: [
    // Document title
    { startIndex: 1, endIndex: 18, style: "heading1" },
    // PR section headings
    { startIndex: 20, endIndex: 45, style: "heading2" },
    { startIndex: 287, endIndex: 325, style: "heading2" },
    // Field labels
    { startIndex: 47, endIndex: 54, style: "bold" },
    { startIndex: 73, endIndex: 80, style: "bold" },
    { startIndex: 89, endIndex: 101, style: "bold" },
    { startIndex: 327, endIndex: 334, style: "bold" },
    { startIndex: 347, endIndex: 354, style: "bold" },
  ]
})
```

### Formatting Best Practices

1. **Always insert text first**, then apply formatting — formatting operates on
   existing text ranges
2. **Calculate indices carefully** — count characters including newlines (`\n`)
3. **Heading styles apply to the entire paragraph** — even if the range covers
   only part of it
4. **Multiple styles can stack** — apply both `heading2` and `bold` to the same
   range for bold headings
5. **Use links for URLs** — apply `link` style with a `url` field instead of
   pasting raw URLs
6. **Format generously** — use heading2 for every major section, bold for every
   label or field name. A document with only a heading1 title and plain text
   body looks unprofessional

## Creating Documents

Use `docs.create` to create new documents:

- **Blank document**: Provide only a `title`
- **Document with content**: Provide `title` and `content` — the content is
  inserted into the document after creation
- **In a specific folder**: Add `folderName` to organize the document

```
docs.create({
  title: "Weekly Status Report",
  content: "Status Report - Week of March 10\n\nHighlights\n\n- ...",
  folderName: "Team Reports"
})
```

## Writing Text

Use `docs.writeText` to add text to an existing document:

- **Append to end** (default): `position: "end"` or omit position
- **Insert at beginning**: `position: "beginning"`
- **Insert at specific index**: `position: "5"` (numeric string)

```
docs.writeText({
  documentId: "doc-id",
  text: "New content\n",
  position: "end"
})
```

## Find and Replace

Use `docs.replaceText` to find all occurrences of a string and replace them.
This works across all tabs by default, or in a specific tab with `tabId`.

## Tab Management

Google Docs supports multiple tabs within a single document.

### Reading Tabs

- **Single tab**: `docs.getText` returns plain text directly
- **Multiple tabs**: Returns JSON array with `tabId`, `title`, `content`, and
  `index` for each tab
- **Specific tab**: Pass `tabId` to read only that tab
- **Nested tabs**: Child tabs are flattened and included in results

### Writing to Tabs

All write tools (`writeText`, `replaceText`, `formatText`) accept an optional
`tabId` parameter:

- **Without `tabId`**: Operates on the first tab (default)
- **With `tabId`**: Operates on the specified tab, including nested child tabs

## Document Organization

### Finding Documents

Use `drive.search` with a document MIME type filter to find Google Docs:

```
drive.search({
  query: "mimeType='application/vnd.google-apps.document' and name contains 'Weekly Report'"
})
```

For full-text search across document content, use `fullText contains` instead of
`name contains`.

### Moving Documents

Use `drive.moveFile` to move a document to a different folder. You can specify
the destination by folder ID or folder name.

## Comments & Suggestions

### Reading Comments

Use `drive.getComments` to retrieve all comments on a document:

- Returns comment threads with author, content, timestamp, and resolution status
- Includes **threaded replies** with author, content, timestamp, and action
  (e.g., `resolve`, `reopen`)
- Includes **quoted file content** showing what text the comment is anchored to

```
drive.getComments({ fileId: "doc-id" })
```

### Reading Suggestions

Use `docs.getSuggestions` to retrieve suggested edits from a document:

- **Insertions** — text proposed for addition (`suggestedInsertionIds`)
- **Deletions** — text proposed for removal (`suggestedDeletionIds`)
- **Style changes** — text formatting changes (bold, italic, etc.)
- **Paragraph style changes** — heading level changes (e.g., NORMAL_TEXT →
  HEADING_2)

Each suggestion includes the affected text, suggestion IDs, and start/end
indices.

```
docs.getSuggestions({ documentId: "doc-id" })
```

## ID Handling

- All tools accept Google Drive URLs directly — no manual ID extraction needed
- IDs and URLs are interchangeable in all `documentId` parameters