google-docs

Files (19)

• SKILL.md
• openai.yaml · agents/
• google-docs-small.svg · assets/
• google-docs.png · assets/
• reference-citations-and-hyperlinks.md · references/
• reference-connector-runtime-and-safety.md · references/
• reference-direct-request-composition.md · references/
• reference-figures-and-image-insertion.md · references/
• reference-foreground-guard.md · references/
• reference-headings-and-question-format.md · references/
• reference-import-docx-to-native-docs.md · references/
• reference-meeting-notes-direct.md · references/
• reference-native-create-direct.md · references/
• reference-pdf-export-visual-qa.md · references/
• reference-request-shapes-and-write-safety.md · references/
• reference-response-and-list-format.md · references/
• reference-section-completeness-and-final-pass.md · references/
• reference-smart-chips-and-building-blocks.md · references/
• reference-table-formatting-deep-dive.md · references/

SKILL.md (first lines)

# Google Docs

Use this skill for Google Docs work in Codex local-plugin sessions.
For blank or basic native Google Docs, create the doc directly with the Google Drive connector. Use `[@documents](plugin://documents@openai-primary-runtime)` plus DOCX import only when the requested deliverable needs polished document authoring, complex layout, visual design, image/figure placement, page-level QA, branded styling, or export-quality fidelity.

## Purpose Of This File

This file is intentionally minimal and covers:

1. connector loading and runtime boundaries in the Codex local-plugin environment
2. the direct native-create route for blank and basic Google Docs
3. the DOCX-first native import route for polished or complex Google Docs
4. the direct-request workflow for existing and newly created Google Docs
5. stateful operation and mandatory routing to reference files

All formatting, citation, table, request-shape, and production rules live in `references/`.
Read only the references required for the task. For the common calendar-backed meeting-notes edit, `references/reference-meeting-notes-direct.md` is the single task reference unless the task adds tables, figures, citations, import/export, or other non-meeting-notes requirements.

## Default Routing

Use this routing:

1. Blank or basic native Google Docs creation: read `references/reference-native-create-direct.md`, call `mcp__codex_apps__google_drive._create_file` with `mime_type: "application/vnd.google-apps.document"`, and use direct Docs `batchUpdate` requests only if content is requested.
2. Polished or complex net-new Google Docs creation: use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx` first, explicitly selecting the `google_docs_default` design preset unless the user asked for a special, branded, or highly polished visual treatment. Then read `references/reference-import-docx-to-native-docs.md` and import with `mcp__codex_apps__google_drive_import_document` using `upload_mode: "native_google_docs"`.
3. If the Documents plugin is unavailable for a polished or complex deliverable, report that the required local Documents authoring path is unavailable. Do not block blank or basic native Google Doc creation on the Documents plugin.
4. Existing Google Docs reads, summaries, edits, comments, and template-preserving modifications: use Google Docs connector or app tools directly.

Choose the simplest creation path that can faithfully satisfy the request. The connector-native path is the default for blank docs and basic documents with plain text, headings, lists, simple links, simple tables, and supported smart chips. The DOCX-import path is the high-quality workflow for deliverables where page layout, figure generation, visual polish, export quality, or full rendered visual QA matter.

The import reference owns the exact connector action, plugin install/reinstall handling, native-conversion verification, post-import normalization, and cleanup steps. Read it before any DOCX-first Google Docs import attempt.

For DOCX-first work, local DOCX staging hygiene is mandatory. Staging must be non-user-visible and untracked from the start. Do not create DOCX builder or helper scripts with tracked file-edit tools such as `apply_patch`, and do not create helper source files in the workspace or any path surfaced by Changes Made. Prefer the Documents plugin's built-in authoring workflow or a one-shot runtime command that keeps generation code ephemeral and persists only the required `.docx`, render outputs, and scratch assets in a per-task scratch directory. After successful native import and connector readback, remove those local staging artifacts unless the user explicitly asked to keep local files. Cleanup is required as a backstop, not as the visibility control.

Do not reference the local `.docx` in the final answer after successful native import. The final answer includes the Google Docs link only.

## Capability Position

Connector-first creation and editing is the preferred path for blank docs, basic native docs, existing native Google Docs, and targeted post-import edits. It is strong for text, headings, bullets, links, simple tables, tabs, comments, supported smart chips, meeting-notes-like building-block reconstruction, and template-preserving insertions.

It is not a universal replacement for DOCX-first creation. Use DOCX-first creation for net-new polished deliverables where page layout, figure generation, export quality, or full rendered visual QA matter.

For template-preserving work, sample the nearest comparable live document structure before writing. Reproduce connector-visible structure and supported element types rather than approximating everything as plain text. For unsupported UI-only constructs, copy an existing template document or recreate the observable constituent structure; do not claim native UI building-block insertion unless connector readback proves it.

## Google Docs Default Preset

For DOCX-first Google Docs creation, `google_docs_default` is the default visual contract. Do not let the Documents skill infer `standard_business_brief`, `compact_reference_guide`, or another Word-oriented preset from the content archetype alone. The expected result is a native-feeling Google Doc after import: Arial-based typography, black title/headings/body text, simple title block, restrained spacing, real lists, and no imported Word-template chrome such as blue headings, colored callouts, dense table borders, or running header/footer furniture.

Use a different Documents preset only when the user explicitly asks for a special visual treatment, a branded document, or a more polished formal artifact than a normal Google Doc.

## Runtime Model

This plugin is for the local Codex plugin environment.

1. Use Google Docs connector or app tools directly from Codex for reads, writes, and verification.
2. Do not use code-mode bridge writes or subprocess connector writes for this skill.
3. Do not run local `gdocs_*` helper scripts to digest `get_document` output or generate `batchUpdate` request arrays.
4. Prepare request JSON directly from connector readback, source data, and the examples in `references/reference-direct-request-composition.md`.
5. Keep connector calls separate from any local helper processing, and do not use embedded-runtime helper snippets or assumed global connector bindings.
6. This environment has no Browser Use or live browser-rendered inspection. Do not require browser foregrounding, screenshots, cursor placement, live rendered-page scans, or visible-tab checks.

## Stateful Operation

Maintain working state for the active document task instead of re-deriving context from scratch after every step.
Keep the target URL, document id, `tabId`, source materials, relevant readback snippets, resolved sections or tables, live indexes, write batches, and verification status current as the task progresses.
Refresh that state before connector writes when source gathering, document switches, connector errors, or runtime resets could make it stale.

## Non-Negotiable Output Invariant

Inserted or edited content must match the surrounding document's existing structure and connector-observable presentation closely enough that it should read as native template content.
This is launch-blocking, not cosmetic. Treat missing section hierarchy, mismatched heading level, font family, font size, bolding, link coverage, table styling, chip type, or template-shape drift visible in connector data as a failed output that must be corrected before handoff. Do not claim rendered visual verification from connector readback or HTML export alone.

When Google Drive PDF export and local PDF page rasterization are available, use the PDF-export visual QA workflow in `references/reference-pdf-export-visual-qa.md` after connector readback for layout-sensitive work. That workflow can verify exported Google Docs PDF pages for clipping, overlap, page breaks, table fit, and figure placement. If PDF export or raster review is unavailable, state the limitation plainly and do not imply rendered visual QA passed.

For presentation-oriented documents, structural completeness is not enough. A document can have all requested sections, headings, tables, and placeholders resolved while still being too dense, monotonous, or hard to scan. Treat readability, hierarchy, and appropriate use of visual devices as part of completion, not as optional polish.

## Canonical Workflow Bias

Prefer one simple proven workflow over a large tree of recovery branches.
When a task matches a known successful pattern, follow that pattern directly instead of re-evaluating every possible insertion or fallback path.
Do not let accumulated edge-case guardrails turn a straightforward document task into a long blocker-analysis exercise.
For net-new Google Doc requests, follow Default Routing first: connector-native for blank/basic docs, DOCX-first for polished/complex deliverables.
For existing document editing tasks, connector-created docs with content, and follow-on edits after a DOCX import, use direct connector `batchUpdate` request composition when viable.

## Direct-Request Workflow

For connector-created docs with content, existing document editing tasks, and follow-on edits after a DOCX import, use this sequence when viable:

1. Gather the required source material.
2. Create or attach to the destination document.
3. Resolve the exact destination `documentId`, URL, and `tabId` if tabs are present.
4. Read the destination through the connector. Use full `get_document` when structure, styles, tabs, tables, chips, or building-block-like content matter.
5. Make compact working notes from the connector response: target section ranges, relevant paragraph start/end indexes, element types, paragraph styles, text styles, table coordinates, list state, and revision id.
6. Sample the local template shape, including paragraph styles, list state, tables, links, and supported chip element types.
7. Compose the smallest clear `batchUpdate` request batch directly in the connector call. Split large or fragile edits into verified batches.
8. Use `write_control.requiredRevisionId` when the write is based on a fresh revision id and collaborator conflicts should fail fast.
9. Re-read the edited area after each substantial write, then continue from live indexes.
10. Verify and normalize formatting, links, chips, tables, and headings before final handoff.

For any secondary element that cannot be verified through connector reads, either use a connector-supported path with readback or clearly state the verification limit.

If a simple verified workflow is viable, use it. Do not drift into speculative alternate paths.

## Meeting-Notes Fast Path

For requests like "add meeting notes for today's/tomorrow's meeting from my calendar":

1. Read only `references/reference-meeting-notes-direct.md` unless the task adds tables, figures, citations, import/export, or other non-meeting-notes requirements.
2. Follow that reference directly; it owns Calendar lookup, Meeting notes shape, empty placeholders, attendee chips, declined-attendee styling, and fast connector readback.
3. Do not export HTML or PDF for this text-only fast path. Connector readback is the verification surface for chips, bullets, headings, and target identity.

## Release-Blocker Checklist

Before final handoff, explicitly verify these with connector readback:

1. every new or edited table has the intended rows, columns, cell text, table anchor, style requests, and column widths where the connector exposes them
2. every new or edited heading, label, and body block matches surrounding connector-visible style fields such as named style, font family, font size, bolding, links, and list state; imported net-new Docs should read back as Arial-based, black-text documents without obvious blue-heading or Word-template residue
3. every new or edited smart chip or building-block-like region preserves connector-visible element types where supported: `dateElement`, `person`, and `richLink`
4. every meeting-notes-like block was composed from sampled peer structure and `references/reference-meeting-notes-direct.md`
5. every inserted figure or image uses a connector-supported insertion path and is present in connector readback; if rendered placement cannot be inspected, say so plainly

From lightspeedwp/.github, GPL-3.0.

More from lightspeedwp/.github