Google Docs authoring

Locate text, never compute indexes (the #1 source of bugs)

Docs edits address zero-based UTF-16 index ranges within one tab, and every write SHIFTS later indexes. Guessed or stale indexes silently hit the wrong paragraphs - the classic symptom is two lists merging into one continued numbering. The tools remove the need for index math:

```
find_text
```
returns FRESH
```
{start, end}
```
ranges for exact text - the direct source of indexes for
```
apply_text_style
```
,
```
apply_paragraph_style
```
,
```
delete_content
```
, and
```
set_paragraph_format
```
. Locate, then edit, in back-to-back calls.
```
create_list
```
takes
```
firstItemText
```
/
```
lastItemText
```
anchors and resolves the range itself: name the first and last item paragraphs and no index ever touches your hands. Use one
```
create_list
```
per list with the right preset (BULLET_* for bullets, NUMBERED_* for numbers); never stretch one call across two visually separate lists.

When a range must come from structure instead of a phrase (styling a whole paragraph, addressing a table), read it from

read_document

elements: a paragraph's

{start, end}

is the range for paragraph-level tools. END IS EXCLUSIVE: one short misses the last character, one long styles the character after the phrase (the classic italic-or-link off-by-one).

When raw indexes are unavoidable:

read_document

first, compute ONE edit, pass

requiredRevisionId

, apply, and re-read before the next positional edit. Order multi-part positional work BACK-TO-FRONT (highest index first) when re-reading between steps is too expensive; earlier ranges stay valid.

Creating a document

create_document

makes a BLANK doc (its API ignores content), so plan:

Content known up front: prefer google-drive
```
google_drive_create_file
```
with Markdown (
```
target_mime_type: ...document
```
), which imports headings, lists, and tables in one call and can target a folder.
Building incrementally:
```
create_document
```
, then
```
insert_text
```
with
```
index
```
omitted to APPEND each paragraph; append mode reads the tail itself and is revision-guarded automatically.
```
paragraphStyle
```
styles the new paragraphs and
```
bold
```
/
```
italic
```
style the inserted text in the same call, so a well-structured document is a sequence of appends with no styling pass.
Doc creates cannot set a parent folder. When placement matters, create and then google-drive
```
google_drive_move_or_rename
```
with
```
destination_folder_id
```
.

Structure is not optional

A document without hierarchy reads as a text dump. Default shape for any report/memo/notes request: a TITLE paragraph, an italic byline or date line, HEADING_2 per section, short body paragraphs with bold on the phrases that matter, and bulleted lists for enumerations. Use

insert_text

's paragraphStyle/bold/italic arguments as you write rather than styling afterwards.

Styling

Character styling (
```
apply_text_style
```
): bold/italic/underline/strike, fontSize, fontFamily, textColor/backgroundColor as
```
#RRGGBB
```
, linkUrl. Exclusive END index: to style one paragraph without its trailing newline, use
```
end - 1
```
from the read.
Paragraph styling:
```
apply_paragraph_style
```
for named styles (TITLE/HEADING_1..6),
```
set_paragraph_format
```
for alignment, indents, and line spacing (percent, 100 = single).
Lists:
```
create_list
```
over the paragraphs' range; each newline-separated paragraph becomes one item. Insert the plain lines first, then bullet them.
The preset is part of correctness: enumerations get a BULLET_* preset by default; NUMBERED_* only when the content is ordered (steps, rankings) or the request says numbered.
Before bulleting, check the read for paragraphs that ALREADY show a leading bullet - text appended directly after a list inherits its membership, and
```
create_list
```
over such paragraphs restyles the ORIGINAL list, continuing its numbering (a second list showing 4, 5, 6). Strip first:
```
create_list
```
with
```
remove: true
```
over exactly the new paragraphs, then apply the wanted preset.

Tables and images

```
insert_table
```
inserts an EMPTY grid. To fill it: re-read (cells appear with their own index ranges) and
```
insert_text
```
into cells from the LAST cell to the first, so earlier cell indexes stay valid.
Style a table AFTER filling it, addressing it by the table element's
```
start
```
from
```
read_document
```
:
```
set_table_cell_shading
```
the header row (pick the row's text color against that fill),
```
merge_table_cells
```
for a title cell spanning columns (top-left content survives, the rest is dropped),
```
set_table_column_width
```
for fixed widths in points. Structural edits (merge) shift indexes: re-read before further text edits.
```
insert_image
```
needs a PUBLICLY fetchable URL (Google fetches it; auth walls and private hosts fail), PNG/JPEG/GIF. Size with width/height in points (aspect kept when only one is set).
```
insert_page_break
```
starts a new page at an index.

Headers and footers

set_header_footer

sets the default header or footer in one call: it creates the segment when the doc has none, replaces the text otherwise, and empty text clears it. The text is static (no page-number fields exist in the API); it applies to the first tab. Never

insert_text

a fake header into the body - it scrolls away with the content.

Bulk text ops

replace_text

replaces literal strings everywhere (or in named tabs) with no index math; prefer it for renames and corrections.

delete_content

rejects ranges that split table structure or surrogate pairs; deleting a paragraph's final newline merges it with the next.

Verify your work

Re-read with

read_document

for structure and styles, or google-drive

google_drive_read_file

for the whole doc as Markdown, or

google_drive_export_file

(pdf) when the visual result matters. After any styling call, confirm the styled span covers exactly the intended text before moving on.

google-docs

NPX Install

Tags

SKILL.md Content