diff --git a/plugins/google-drive/skills/google-docs/SKILL.md b/plugins/google-drive/skills/google-docs/SKILL.md index af7f3f8e..3740edf1 100644 --- a/plugins/google-drive/skills/google-docs/SKILL.md +++ b/plugins/google-drive/skills/google-docs/SKILL.md @@ -6,7 +6,7 @@ description: Documents-first net-new Google Docs creation plus connector-first G # Google Docs Use this skill for Google Docs work in Codex local-plugin sessions where Browser Use and rendered visual inspection are unavailable. -Net-new Google Doc deliverables must be authored through `[@documents](plugin://documents@openai-primary-runtime)` as local `.docx` files first, then uploaded as native Google Docs. +Net-new Google Doc deliverables must be authored through `[@documents](plugin://documents@openai-primary-runtime)` as local `.docx` files first, using the `google_docs_default` design preset by default, then uploaded as native Google Docs. ## Purpose Of This File @@ -22,13 +22,21 @@ Latency is not a constraint for this skill, so always read the relevant referenc Use this routing: -1. Net-new Google Docs creation: use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx` first, including that skill's DOCX QA workflow. -2. Upload and convert the `.docx` into Drive as a native Google Docs document. Read `references/reference-import-docx-to-native-docs.md`. +1. 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. +2. Upload and convert the `.docx` into Drive as a native Google Docs document. Read `references/reference-import-docx-to-native-docs.md`, then run the repair-only post-import normalization pass described there. 3. If the Documents plugin is unavailable, do not create the net-new Google Doc directly. Report that the required local Documents authoring path is unavailable. 4. Existing Google Docs reads, summaries, edits, comments, and template-preserving modifications: use Google Docs connector or app tools directly. +Local DOCX staging hygiene is mandatory for net-new Google Docs. 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. +## Google Docs Default Preset + +For a net-new Google Doc, `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. @@ -64,7 +72,7 @@ For existing document editing tasks and follow-on edits after a DOCX import, pre 3. establish the heading and section skeleton 4. fill the core text or structured content 5. decide which content should stay prose, become a table, become a short card, or become a compact visual block -6. verify and normalize formatting +6. verify and normalize formatting, including the repair-only Google Docs post-import pass for imported DOCX files 7. add secondary elements such as tables, links, or connector-supported figures only after the core structure is stable 8. stop once the document is clean, complete, and scannable @@ -77,7 +85,7 @@ If a simple verified workflow is viable, use it. Do not drift into speculative a 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 +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 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 4. when available, export the document as `text/html` through Google Drive and use the generated markup/CSS as a rendered-structure proxy for heading tags, font families, font sizes, table cells, fills, widths, and paragraph ordering 5. the document is not relying on one repeated structure everywhere; for example, a long run of similar tables or identical header colors should be treated as a design smell unless the source template clearly calls for it @@ -94,6 +102,7 @@ If Default Routing uses `[@documents](plugin://documents@openai-primary-runtime) 1. Read the `[@documents](plugin://documents@openai-primary-runtime)` plugin skill. 2. Read `references/reference-import-docx-to-native-docs.md`. +3. For the post-import normalization pass, also read `references/reference-request-shapes-and-write-safety.md`, `references/reference-headings-and-question-format.md`, `references/reference-response-and-list-format.md`, and `references/reference-section-completeness-and-final-pass.md`. If Default Routing uses connector edit workflow: diff --git a/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md b/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md index 625740d7..167be480 100644 --- a/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md +++ b/plugins/google-drive/skills/google-docs/references/reference-import-docx-to-native-docs.md @@ -7,7 +7,7 @@ description: Import a local DOCX as a native Google Docs document. When to read: after creating or locating a local `.docx` file that should become a native Google Docs document. -For new Google Docs creation, create the local document with the `[@documents](plugin://documents@openai-primary-runtime)` plugin first, then follow this import path. +For new Google Docs creation, create the local document with the `[@documents](plugin://documents@openai-primary-runtime)` plugin first, explicitly selecting the `google_docs_default` design preset unless the user asked for a special, branded, or highly polished visual treatment, then follow this import path. ## Native Conversion @@ -17,7 +17,9 @@ For `.docx` inputs, the blessed path is the Google Drive upload tool with `mime_ Steps: 1. Confirm the local source path is an absolute path to a `.docx` file. -2. Upload the file with the Google Drive connector upload tool: +2. Confirm the local staging path is a per-task scratch directory, not the user-facing workspace root. +3. Confirm no persistent DOCX builder or helper source file was created with tracked file-edit tools such as `apply_patch`, and no helper source file lives in a path surfaced by Changes Made. If generation logic is needed, use the Documents plugin's built-in tooling or a one-shot runtime command that keeps the code ephemeral and writes only the `.docx` and required QA outputs into scratch space. If a tracked helper file was already created, regenerate through untracked scratch before upload unless the user explicitly asked to keep that file. +4. Upload the file with the Google Drive connector upload tool: ```json { @@ -27,10 +29,27 @@ Steps: } ``` -3. Use the connector function exposed in the current runtime, for example `mcp__codex_apps__google_drive._upload_file(...)` or the equivalent Google Drive upload tool. -4. Verify the upload response reports native conversion with `mime_type: "application/vnd.google-apps.document"` and a Google Docs URL or document id. -5. If the desired Google Doc title should not include `.docx`, rename the native Google Doc with `mcp__codex_apps__google_drive._update_file(...)` or the equivalent Drive metadata update tool after upload. -6. Read the imported document with the Google Docs connector and verify that core headings, body text, tables, and other connector-visible content survived conversion. +5. Use the connector function exposed in the current runtime, for example `mcp__codex_apps__google_drive._upload_file(...)` or the equivalent Google Drive upload tool. +6. Verify the upload response reports native conversion with `mime_type: "application/vnd.google-apps.document"` and a Google Docs URL or document id. +7. If the desired Google Doc title should not include `.docx`, rename the native Google Doc with `mcp__codex_apps__google_drive._update_file(...)` or the equivalent Drive metadata update tool after upload. +8. Read the imported document with the Google Docs connector and verify that core headings, body text, tables, and other connector-visible content survived conversion. +9. Run the repair-only post-import normalization pass below. +10. After successful connector readback and normalization, clean up local staging artifacts: generated render folders, QA PNG/PDF files, temporary assets, and the local `.docx` source. Keep local files only when the user explicitly asked to preserve them. Cleanup is a final backstop and does not replace the requirement to avoid tracked helper files before upload. + +## Post-Import Normalization + +Use this only for imported net-new Google Docs created from the Documents plugin. The goal is to repair conversion drift, not to create a second styling system. + +1. Re-read the imported document and sample the title, the first real section heading, one body paragraph, and the first list if present. +2. Verify the imported document still matches the `google_docs_default` intent: + - title/headings/body text use Arial or the closest connector-visible Arial family + - text color is black for title, headings, body, and lists + - section hierarchy is preserved with real Docs heading styles + - bullets and numbered items are real Docs lists, not typed markers + - no obvious Word-style residue survived import: blue heading colors, decorative running headers/footers, colored callout fills, dense table borders, or table-first packaging of normal prose +3. If any of those checks drifted during import, use the normal Google Docs connector write path to repair only the affected ranges. Prefer `updateParagraphStyle`, `updateTextStyle`, `createParagraphBullets`, `deleteParagraphBullets`, `updateTableCellStyle`, and other narrow native requests instead of broad rewrites. +4. Re-read the repaired ranges and, when available, export `text/html` as a structure/style proxy to confirm the imported document now reads like a native Google Doc. +5. Do not add smart chips, metadata pills, decorative mastheads, or new styling flourishes in this pass. Those are out of scope for v1. ## Preservation Mode diff --git a/plugins/google-drive/skills/google-drive/SKILL.md b/plugins/google-drive/skills/google-drive/SKILL.md index a2558ae4..34ab3c90 100644 --- a/plugins/google-drive/skills/google-drive/SKILL.md +++ b/plugins/google-drive/skills/google-drive/SKILL.md @@ -34,7 +34,7 @@ Start with Google Drive for file discovery and file lifecycle tasks, then route - Deck -> Slides skill - If the user wants to find a file and then edit it, do both in one flow: Drive for discovery, then the file-type skill for the edit. - If the user wants a Google Workspace outcome but has not named a file type yet, start with Drive discovery instead of asking them to choose among separate Google plugins. -- If the user asks to create a new Google Doc, route to the Docs skill. The Docs skill must use `[@documents](plugin://documents@openai-primary-runtime)` to create a local `.docx`, then upload and convert it as a native Google Doc. +- If the user asks to create a new Google Doc, route to the Docs skill. The Docs skill must use `[@documents](plugin://documents@openai-primary-runtime)` with the `google_docs_default` preset to create a local `.docx`, avoid tracked DOCX builder/helper scripts or files surfaced by Changes Made, stage only required outputs in per-task scratch space, then upload and convert it as a native Google Doc, run the narrow post-import normalization pass, and clean up local staging files after connector readback. - If the user asks to import a local `.docx` into Google Docs, route to the Docs skill and use native Google Docs conversion by default. Preserve the source file type only when the user explicitly asks for that. - If the user asks to create a new Google Sheet, route to the Sheets skill. The Sheets skill should prefer the `[@spreadsheets](plugin://spreadsheets@openai-primary-runtime)` plugin or `$Excel` skill to create a local `.xlsx`, then import it as native Google Sheets. - If the user asks to import a local `.xlsx`, `.xls`, `.ods`, `.csv`, or `.tsv` into Google Sheets, route to the Sheets skill and use native Google Sheets conversion by default. Preserve the source file type only when the user explicitly asks for that.