Google Docs Formatter

Use this skill to format or update Google Docs through the existing gog skill/CLI. This skill is instruction-only: do not introduce new API clients, scripts, dependencies, or credential flows.

Core rule

Rely on gog for all Google Docs and Drive operations. If the gog skill is not loaded and command details are needed, load the gog skill first.

Prefer Google Docs-native workflows over DOCX conversion. Avoid third-party proxy services unless the user explicitly requests them.

Safety and approval

Before any write operation, state the target document and intended change, then get explicit user approval unless the user has already clearly approved that exact change.

Always ask before:

• gog docs clear
• replacing the full document body
• large multi-section replacements
• deleting text ranges
• changing a shared/work document whose ownership or audience is unclear

Safe to do without extra approval when already working on the user-approved doc:

• inspect metadata/structure
• export/read content
• prepare Markdown locally
• run dry-run style checks if supported

Standard workflow

1. Identify the target doc.

   • Accept a Google Docs URL or document ID.
   • Extract the ID from URLs like https://docs.google.com/document/d/<DOC_ID>/....

2. Inspect before editing.

   gog docs info <DOC_ID> --json
   gog docs structure <DOC_ID>
   gog docs export <DOC_ID> --format md --out /tmp/doc.md
   

3. Decide the edit strategy.

   • New document from Markdown: use gog docs create --file.
   • Replace a known placeholder or section: use gog docs find-replace --format markdown.
   • Small textual fix: use gog docs edit or gog docs sed.
   • Append content: use gog docs write --append or gog docs insert.
   • Full rewrite: only after explicit approval; prefer creating a copy first.

4. Prepare content as Markdown.

   • Use Markdown headings, bullets, numbered lists, tables, bold/italic, and links.
   • Keep semantic structure simple; Google Docs conversion is more reliable with clean Markdown.
   • For images, use supported Markdown image syntax only if gog docs create / find-replace --format markdown supports the source.

5. Apply the change with gog.

6. Verify after editing.

   gog docs structure <DOC_ID>
   gog docs export <DOC_ID> --format md --out /tmp/doc-after.md
   

   Compare the exported Markdown or structure against the intended result.

7. Report concisely.

   • What changed
   • Any limitations observed
   • Link or doc ID if useful

Common operations

Create a formatted Google Doc from Markdown

Prepare a local Markdown file, then:

gog docs create "Document title" --file /path/to/content.md

Use this instead of Markdown → DOCX → Drive upload unless the user specifically needs DOCX behavior.

Replace a placeholder with formatted Markdown

Best when the document contains a marker such as {{SECTION_DRAFT}}.

gog docs find-replace <DOC_ID> '{{SECTION_DRAFT}}' --content-file /path/to/section.md --format markdown --first

Prefer --first when replacing a unique placeholder to avoid accidental repeated changes.

Replace an existing section

If possible, first ask the user to add or approve stable markers around the section:

<!-- START: SECTION_NAME -->
old content
<!-- END: SECTION_NAME -->

Then replace the bounded content with gog docs find-replace --format markdown using a prepared Markdown file.

If there are no stable markers, use gog docs structure to identify paragraphs and proceed carefully. Do not guess destructive ranges.

Small text edits

gog docs edit <DOC_ID> "old text" "new text" --match-case

For regex-style replacements:

gog docs sed <DOC_ID> 's/old pattern/new text/g'

Use regex edits only when the match is unambiguous.

Append content

gog docs write <DOC_ID> --file /path/to/content.md --append

If Markdown formatting is required, prefer placeholder replacement with --format markdown when available.

Full document rewrite

Only after explicit approval. Prefer making a copy first:

gog docs copy <DOC_ID> "Backup before rewrite"
gog docs clear <DOC_ID>
gog docs write <DOC_ID> --file /path/to/content.md

Tell the user if the write path preserves only text rather than rich Markdown formatting; use create --file or find-replace --format markdown for rich Markdown conversion.

Formatting guidance

Use simple, robust Markdown:

# Title

## Section

Short paragraph.

- Bullet one
- Bullet two

| Column A | Column B |
| --- | --- |
| Value A | Value B |

**Bold** and *italic* text.

Avoid fragile formatting unless tested:

• deeply nested lists
• complex merged tables
• unusual HTML
• custom fonts/colors not expressible through Markdown

For advanced visual formatting not supported by gog, explain the limitation and propose the nearest gog-supported alternative.

When to stop and ask

Ask the user before proceeding if:

• the document ID is ambiguous
• the requested formatting requires capabilities not exposed by gog
• the edit would delete or overwrite substantial content
• the exported/inspected structure does not match expectations
• gog reports auth/scope errors

Do not install other Google Docs skills just to complete formatting. This skill is meant to compose with gog, not replace it.