Google Drive

View saved version →

---
name: google-docs
description: Prompt- and template-complete Google Docs creation and editing with explicit-instruction-authoritative structural preservation, including semantic roles, relationships, comparison dimensions, and instructed extensions; full-topology native-copy routing; source-grounded per-tab adaptation for past/example references; style-preserving hyperlink and table edits; canonical smart-chip-first authoring for dates and relevant supported people or Google resources; a file-backed advisory trusted read before existing-document writes; automatic protected-control awareness; direct connector APIs by default; DOCX-first import only when no supplied Google Doc template/reference constrains the output; and checked-in code mode only for exact native dropdown mutation. Use when Codex must create, edit, fill, adapt, redesign, or verify Google Docs without overriding explicit user/template instructions, adding unrequested document scope, or carrying stale reference facts into a new deliverable.
---

# Google Docs

Use this opt-in skill for Google Docs work in Codex local-plugin sessions. Draft once to the requested final shape, prove explicit prompt/source/template coverage, then compress repetition without removing unique requirements.

Code mode is preferred for the checked-in helpers below, but it is not a prerequisite for this workflow. If code mode is unavailable, reproduce the same routing, read and inventory, preservation, mutation, and verification workflow with the available connector or app tools; preserve all checks and adapt any operation without a non-code implementation to the closest supported equivalent, clearly disclosing any unavoidable fidelity difference.

### Documents clarification questions

- Ask for new documents or major rewrites. Skip this for edits/conversions.
- Inspect prompt, conversation history, existing file and relevant references to figure out what questions to ask.
- Questions should cover topic, audience, and purpose and come before planning
- When asking questions, focus on consequential dimensions not stated or clearly implied.
- When the artifact is a new analysis, focus on which definition, metric, or lens should drive conclusions.
- Unresolved reference labels or question marks are user-owned: ask, don't infer.
- Once topic, audience, and purpose are clear, proceed without asking. Choose emphasis, format, length, style, details. Use placeholders for missing facts.

Use `request_user_input` once if available, else ask via a message. Have the best suggestion first. Append `(Recommended)` to its label. Have another good alternative second. Have `Use your judgment` as the third and final option. If the request times out or returns no answer, proceed using your best judgment; do not ask again.

## Default Routing

Choose the route only after resolving whether a supplied Google Doc is a template, reference, example, or content-only source:

1. **Supplied Google Doc template or reference:** read `references/reference-template-preservation-and-edit-scope.md`, inspect the native reference signature below, and remain on a native Google Docs route. Do not delegate authoring to DOCX.
   - Exact template replacement: copy the native document and replace content inside the copied structure.
   - Template extension or adaptation: copy the native document, then make only the required native additions, removals, or expansions.
   - Selective reference use: choose this only when the user explicitly asks to borrow selected parts. Use a native copy and prune it, or create a native Google Doc directly when the selected parts contain no native structure that must be carried forward.
   - Multi-tab invariant: when the supplied document has more than one tab, start from a full native copy and preserve the complete tab tree—tab count, titles, order, and parent/nesting—unless the user explicitly requests a single-tab result, identifies selected tabs/parts to borrow, or directs removal. A URL that opens one tab and wording such as “use this as a reference” do not authorize collapsing the document.
   - Structural preservation and content treatment are separate decisions. Structural preservation covers both native form and semantic organization: tab topology, section order, container identity and position, field roles, table row and column roles, comparison dimensions, ordering, dependencies, and operative instructions embedded in or adjacent to retained structures. It does not freeze the initial dimensions; when the user or template directs an extension, deletion, substitution, or reordering, perform that change inside the native structure. Applicable user and template instructions take precedence over this skill's layout, compaction, and styling defaults; those defaults apply only where the governing sources are silent. For a past/example reference used to build a new deliverable, retained tabs preserve their native structure and styling but default to `adapt content`; they do not preserve prior-project facts, people, dates, links, approvals, or copy. A “legacy,” “reference,” or “do not use” label does not make stale content acceptable in the finished artifact.
2. **Blank or basic net-new native creation without a constraining Google Doc template/reference:** read `references/reference-native-create-direct.md`, create the file with `mcp__codex_apps__google_drive._create_file`, and use direct Docs `batchUpdate` requests when content is requested.
3. **Polished or layout-sensitive net-new creation without a constraining Google Doc template/reference:** use `[@documents](plugin://documents@openai-primary-runtime)` with the `google_docs_default` preset, then read `references/reference-import-docx-to-native-docs.md` and import as native Google Docs. A supplied Google Doc template/reference disqualifies this route even when the requested result is polished; a content-only source does not. After import, replace mandatory chip-eligible values with native chips during post-import normalization.
4. **Existing document reads, summaries, edits, comments, and preservation-only work:** use Google Docs connector or app tools directly. Before the first write to an existing document, use the checked-in file-backed trusted read described in `references/reference-trusted-read-wrapper.md`; inspect its compact control warning immediately and read normalized document content from the returned file path. Targeted follow-up reads may use connector tools directly.
5. **Exact native dropdown creation, option replacement, or selected-value mutation:** use the checked-in Google Docs dropdown workflow for every mutation in the task after capability discovery. Read `references/reference-dropdown-code-mode.md`.

When the prompt is ambiguous, default to native copy-and-adapt rather than selective borrowing or DOCX reconstruction. Do not create a blank destination or begin a DOCX draft before this decision.

### Native reference signature

Before planning content for a supplied Google Doc template/reference:

1. Read full document metadata and enumerate every tab before reading a single tab in depth: tab id, title, parent, nesting, and order. A URL ending in `?tab=t.0` identifies the initially visible tab, not the full reference scope.
2. Record a compact signature for relevant heading roles: named style, font family, size, weight, color, and spacing.
3. Record each relevant table's tab, shape, semantic row and column roles, comparison dimensions, applicable instructions in or adjacent to the table, borders, fills, padding, widths, and representative text styling.
4. Record relevant native elements and their locations: people/date/rich-link chips, links, images, lists, controls, headers, and footers.
5. Give every tab two treatments: a structural treatment (`retain`, `extend`, `reorder by user direction`, or `remove by user direction`) and a content treatment (`carry current content`, `adapt`, `replace`, or `clear`). Unmentioned tabs default to `retain structure`; when the reference describes a different project, event, product, experiment, incident, or time period, their content defaults to `adapt`, never carry.
6. Record reference-only factual signatures that must not leak into a new deliverable: prior names and organizations, product/project identifiers, dates and times, venues, links and chips, owners and approvers, claims, metrics, statuses, and distinctive copy. The user prompt governs the requested outcome; applicable instructions in the selected template/reference govern how retained structures must be used or adapted; designated content sources govern facts. Skill defaults apply only where those authorities are silent. A template/reference governs facts only when the user explicitly makes its content authoritative.

Do not flatten paragraphs across tabs until the tab tree is recorded. If a full response is too large or truncated, request `tabs(tabProperties)` first and inspect relevant tabs individually. For exact-template and template-adaptation work, use the Drive copy action exposed by the current runtime, then run the file-backed trusted read on the copied destination before its first write. If native copy is unavailable and tabs, styles, chips, controls, or other native semantics matter, stop rather than silently rebuild through DOCX.

Do not block blank or basic eligible creation on the Documents plugin. For eligible DOCX-first work, keep staging untracked and non-user-visible, clean it after successful native import and readback, and return only the Google Docs link unless the user requested local files.

### Documents location

Use/create `ChatGPT` at My Drive root. Place new documents created from scratch or from a template there.
Edit existing documents in place.

Respect user-specified locations.

## Coverage-First Authoring Contract

1. Derive completeness only from explicit user requirements, supplied source content the user asks to carry forward, and applicable template/reference instructions, fields, containers, or functional sections.
2. Before drafting, keep a compact in-memory coverage map with: obligation, authority (`prompt`, `source`, or `template/reference`), required output form, planned destination, and final state (`present`, `unavailable-with-disclosure`, or `omitted-by-explicit-user-direction`). Distinguish factual authority from structural authority: a past/example reference may authorize form, semantic organization, instructions, and style without authorizing any of its facts. Do not persist, serialize, count, hash, or script-validate the map.
3. Use document archetypes only to organize requested material. They never create obligations, sections, evidence requirements, or depth by themselves.
4. Draft once toward the intended final shape; do not create an intentionally maximal draft. Prove coverage before optimizing length.
5. Research externally only when requested, when current/time-sensitive facts are material, or when supplied sources cannot support required factual accuracy. For requested evidence, follow `references/reference-citations-and-hyperlinks.md`.
6. Include methodology, assumptions, alternatives, risks, or sensitivity only when requested or materially necessary to satisfy an obligation.
7. Compress repeated wording and duplicated rationale only after coverage passes. Never remove or merge a unique requirement, requested fact/citation/source, template instruction, field or functional section, distinct decision/owner/dependency/risk/action, comparison dimension, or requested native structure merely to shorten the document.
8. If complete content cannot meet an explicit page limit without unreadable text or a typography-floor violation, report the conflict rather than silently omit content.
9. Never fill a missing fact from a past/example reference merely because its slot needs content. Use the current source, a clearly labeled recommendation, or an explicit unavailable/TBD disclosure. Do not carry a reference-only schedule time, person, link, metric, status, or claim into the new artifact.

Do not use required-unit or evidence ledgers, evidence-level classifications, archetype completeness budgets, document-mode contracts, typography exception ledgers, density-trigger ledgers, a draft-everything-then-compress workflow, or automatic depth based only on document category.

## Native Smart-Chip Authoring Invariant

Use native smart chips whenever the connector supports them and the source contains the required semantic value. The following cases are mandatory, not optional polish:

1. Insert every concrete semantic date added to the document as a `dateElement` with `insertDate`, including dates in prose, metadata fields, lists, and tables. Do not newly type a date as plain text. If the source does not identify the date precisely enough to produce a faithful timestamp, do not invent missing date components; preserve an existing ambiguous value or surface the ambiguity.
2. First decide whether a person belongs in the finished document. For every template/reference person chip, classify the role as `carry forward`, `replace from source`, or `remove as example/project-specific content`. Do not preserve a person merely to retain a chip count, and do not discard a reusable/current template contact merely because the task source omits them. When a relevant person name remains or is added and a verified email address is available, use a `person` chip with `insertPerson`. Use plain text only when no email is available, and never guess an address.
3. When a Google Calendar event URL is available, represent the event with a `richLink` chip using `insertRichLink`. Keep descriptive context outside the chip rather than duplicating the raw URL.
4. Represent every link to a Google Doc, Google Sheet, or Google Slides presentation as a `richLink` chip using `insertRichLink`, including links in narrative text, tables, citations, source lists, and appendices. This applies to copied existing links as well as newly inserted links. Canonicalize every retained Workspace URI with `scripts/canonicalize_google_workspace_url.mjs`; replace relevant noncanonical rich links, remove irrelevant reference-era links, and use the canonical file URL without account-routing segments, share parameters, tab/range/heading/slide queries, or fragments. When a location-specific deep link is materially useful, keep the canonical file chip and add a separate readable ordinary hyperlink for that location. Never leave an ordinary Workspace hyperlink as the sole representation.

For other supported Google resource URLs, prefer a `richLink` when it is convenient and improves scanning. Plan chip positions while composing the text skeleton, account for each chip's one-code-unit range, and verify the native element type and properties after writing. These requirements apply to direct-native, copied-template, existing-document, and post-import workflows. Read `references/reference-smart-chips-and-building-blocks.md` and the request examples in `references/reference-direct-request-composition.md` before the first chip write.

## Launch-Blocking Output Invariant

A result is incomplete if it silently omits an explicit requirement, requested source content, template/reference field, required link or figure, requested native structure, mandatory smart chip, or distinct functional section. Matching visible text is not enough when native semantics are required. These are content failures, not optional polish.

Unavailable information may remain visibly TBD or be disclosed only when the source truly lacks it. Preserve unsupported native structures by copy, use an explicitly approved fallback, or stop before destructive work. A shorter document is not automatically better.

## Runtime And Dropdown Route

Direct connector execution is the default. Do not use ad hoc code-mode bridges, subprocess connector writers, private Google RPCs, browser/UI writers, model-authored executable helpers, or `google-docs-cm`.

Resolve dropdown intent before the first write:

| Task | Route |
| --- | --- |
| No dropdown involvement | Direct connector |
| Preserve an existing dropdown | Direct connector with targeted preservation |
| Create a native dropdown | Checked-in Google Docs dropdown code mode |
| Replace dropdown options | Checked-in Google Docs dropdown code mode |
| Change selected value | Checked-in Google Docs dropdown code mode |
| Text/table edits plus dropdown mutation | Dropdown code mode owns every mutation |
| Required dropdown tools unavailable | Stop before exact mutation |

Exact mutation requires runtime discovery of both `getDocumentDropdowns` and `updateDocumentDropdown`. Public Docs `batchUpdate` cannot prove dropdown semantics. Once dropdown code mode is selected, do not switch writers mid-task.

## Direct-Request Workflow

For native copies, connector-created docs with content, existing-document edits, and post-import repairs:

1. Gather the requested source material.
2. Copy, create, or attach to the destination document according to the resolved route.
3. Resolve the exact document id, URL, complete tab tree, active `tabId`, and current revision where exposed.
4. For the first full read before writing an existing document, invoke `host/docs-trusted-read-file-bridge.mjs` exactly as described in `references/reference-trusted-read-wrapper.md`. It persists the raw response, control inventory, machine-readable outline, and annotated model-readable text while returning automatic advisory control awareness. Do not transport the raw response with `text()` or `apply_patch`.
5. Read the returned `document_text` artifact, inspect `controlAwareness`, and record compact working notes for target ranges, nearby styles, table coordinates, native elements, revision, and preservation warnings. Read the raw result only when normalized artifacts omit a required field.
6. For template/reference work, compare the copied destination against the native reference signature before drafting. If the source has multiple tabs, confirm the destination already has the same complete tab topology before any content write; do not proceed from a blank or single-tab destination. Apply the separate structural/content treatment for every tab, and do not finish one tab while leaving other retained tabs as historical reference material. For structured existing-document work, use the targeted snapshot in `references/reference-template-preservation-and-edit-scope.md`.
7. Classify every planned and copied semantic date, relevant known-email person, Google Calendar event URL, and Google Docs/Sheets/Slides URL; canonicalize retained Workspace file URLs and allocate mandatory `insertDate`, `insertPerson`, or `insertRichLink` requests rather than emitting plain text or ordinary hyperlinks.
8. Compose the smallest clear `batchUpdate` request batch. Split large or fragile edits into verified batches.
9. Use `write_control.requiredRevisionId` when a fresh revision should fail fast on collaborator conflicts.
10. Re-read after substantive or index-shifting writes and continue from live indexes.
11. Reconcile the coverage map, then verify and repair requested content and connector-observable presentation before final handoff.

Do not rebuild an entire document to perform a targeted edit. If a native component cannot be safely preserved or verified, stop before destructive work and report the limitation.

## Stateful Operation

Keep the target URL, document id, tab tree, active `tabId`, source materials, relevant readback, live ranges, write batches, and verification status current. Refresh state after document switches, source gathering, connector errors, or runtime resets.

## Meeting-Notes Fast Path

For calendar-backed meeting-notes requests, read only `references/reference-meeting-notes-direct.md` unless the task adds tables, figures, citations, import/export, or other requirements. Use connector readback—not HTML or PDF—as the verification surface for this text-only path.

## Universal Completion Checks

Before handoff, verify:

1. the target document and complete tab topology are correct; for a multi-tab template/reference, every source tab has both its planned structural treatment and its completed content treatment, or an explicit user-authorized removal
2. every coverage-map obligation is present, explicitly unavailable, or omitted only by user direction
3. required source content and template/reference fields are in the intended location and form
4. relevant heading and table style signatures match the template/reference except for intentional changes; expanded tables reuse the canonical peer's header/body cell styles, borders, fills, padding, widths, and typography
5. headings, body text, native links, tables, figures, and lists are coherent and readable
6. every mandatory chip opportunity is represented by `dateElement`, `person`, or canonical `richLink` as applicable; copied relevant rich links are canonicalized, no ordinary Docs/Sheets/Slides hyperlink is the sole representation, each retained person chip passed the relevance decision, and relevant existing chips, native controls, and other native elements read back with the correct connector-visible semantics
7. each retained tab is source-current; no reference-only facts, obsolete names/chips, dates, times, links, claims, statuses, distinctive prior-project copy, placeholders, duplicate sections, accidental empty bullets, or scaffolding remain. Historical content may remain only when the user explicitly requested it
8. every ordinary hyperlink preserves the sampled surrounding font family, size, weight, emphasis, color, underline state, and paragraph role after readback
9. no unrelated source or template structure changed
10. layout-sensitive work passed final PDF visual QA, or the unavailable verification is stated plainly

Run feature-specific checks only for features used: evidence targets, template/reference semantic inventory, dropdown metadata, table-cell native lists, explicit global formatting, branded furniture, figures, or layout-sensitive rendering. Semantic reconciliation may reopen content scope to repair an omission; formatting repair may not unless it exposes one. During evaluation, classify repairs as prompt/content omission, source/template omission, native-structure fidelity, targeting, formatting, or pagination/layout.

## Required Read Order

Before writing, read only the references selected by the active route:

- Blank native doc: `references/reference-native-create-direct.md`.
- Basic native doc with content: `references/reference-native-create-direct.md` and `references/reference-direct-request-composition.md`.
- Supplied Google Doc template/reference: `references/reference-template-preservation-and-edit-scope.md` before choosing a construction route; do not use DOCX-first import.
- DOCX-first import for eligible reference-free creation: the Documents skill and `references/reference-import-docx-to-native-docs.md`; use task-specific references for requested shapes, evidence, or post-import repairs.
- Calendar-backed meeting notes: `references/reference-meeting-notes-direct.md`.
- Simple text or supported-chip edit: `references/reference-direct-request-composition.md`.
- Any output containing a semantic date, a person whose verified email is available, a Google Calendar event URL, or a Google Docs/Sheets/Slides URL: `references/reference-smart-chips-and-building-blocks.md` and `references/reference-direct-request-composition.md`.
- Any Google Docs/Sheets/Slides URL with account-routing, sharing, tab, range, heading, bookmark, or slide-specific parameters: run `scripts/canonicalize_google_workspace_url.mjs` before `insertRichLink`.
- First write to an existing Google Doc: `references/reference-trusted-read-wrapper.md`; use the file-backed bridge for the initial full read, then continue on the selected direct or dropdown route.
- Non-meeting structural edit: `references/reference-connector-runtime-and-safety.md`, `references/reference-foreground-guard.md`, `references/reference-request-shapes-and-write-safety.md`, and `references/reference-direct-request-composition.md`.
- Existing structured document, template/reference adaptation, tab duplication, branded furniture, or work near native controls: also `references/reference-template-preservation-and-edit-scope.md` and, when an explicit output form is requested, `references/reference-request-shapes-and-write-safety.md`.
- Research, current facts, metrics, citations, benchmarks, or source links: `references/reference-citations-and-hyperlinks.md`.
- Non-simple chip, dropdown, or building-block work: also `references/reference-smart-chips-and-building-blocks.md`.
- Exact dropdown create/options/selection mutation: `references/reference-dropdown-code-mode.md`, `references/reference-template-preservation-and-edit-scope.md`, and `references/reference-smart-chips-and-building-blocks.md`.
- List inside a table cell or boxed section: also `references/reference-response-and-list-format.md` and `references/reference-table-formatting-deep-dive.md`.
- Explicit formatting of all/every/throughout analogous tables: `references/reference-request-shapes-and-write-safety.md` and `references/reference-table-formatting-deep-dive.md`.
- Layout-sensitive, table-heavy, figure-heavy, polished, or final-deliverable work: `references/reference-section-completeness-and-final-pass.md` and `references/reference-pdf-export-visual-qa.md` before handoff.

Do not bulk-read the reference folder. Do not execute content writes until route-required references are read in the current turn.

## Connector Safety

1. Confirm the exact target document, complete tab tree, and active `tabId` before writes.
2. Resolve the section, table, cell, paragraph, or native control from current connector readback.
3. Use full `get_document` when styles, lists, tables, chips, tabs, headers, footers, or native controls matter; use targeted reads only for simple unambiguous text.
4. Use `get_tables` before table creation, population, list-in-cell work, or global table formatting.
5. Re-read after insertions, deletions, table changes, native-control changes, or other index-shifting operations.
6. Create a native copy before adapting a reusable Google Doc template/reference; edit an explicitly targeted working document in place.
7. Never claim a connector or native feature is unavailable without current-run capability evidence.

## Task Reference Map

| Task area | Reference |
| --- | --- |
| Blank/basic native creation | `references/reference-native-create-direct.md` |
| Runtime attachment and recovery | `references/reference-connector-runtime-and-safety.md` |
| File-backed trusted read, automatic control awareness, and normalized document content | `references/reference-trusted-read-wrapper.md` |
| DOCX import without a constraining Google Doc template/reference | `references/reference-import-docx-to-native-docs.md` |
| Target confirmation | `references/reference-foreground-guard.md` |
| Request shapes and range safety | `references/reference-request-shapes-and-write-safety.md` |
| Direct request examples and supported chips | `references/reference-direct-request-composition.md` |
| Headings and question formatting | `references/reference-headings-and-question-format.md` |
| Lists, including lists inside table cells | `references/reference-response-and-list-format.md` |
| Citations and hyperlinks | `references/reference-citations-and-hyperlinks.md` |
| Template and edit-surface preservation | `references/reference-template-preservation-and-edit-scope.md` |
| Chips, dropdown preservation, and building blocks | `references/reference-smart-chips-and-building-blocks.md` |
| Exact dropdown mutation | `references/reference-dropdown-code-mode.md` |
| Tables and explicit global table formatting | `references/reference-table-formatting-deep-dive.md` |
| Figures and images | `references/reference-figures-and-image-insertion.md` |
| Final structural and visual QA | `references/reference-section-completeness-and-final-pass.md` |
| Native PDF visual QA | `references/reference-pdf-export-visual-qa.md` |

Referenced files: 37

View saved version →

---
name: google-drive
description: Use connected Google Drive as the single entrypoint for Drive, Docs, Sheets, and Slides work. Use when the user wants to find, fetch, organize, share, export, copy, or delete Drive files, or summarize and edit Google Docs, Google Sheets, and Google Slides through one unified Google Drive plugin.
---

# Google Drive

Use this as the top-level router for Google file work inside the unified Google Drive plugin. Do not route the user toward separate Google Docs, Google Sheets, or Google Slides plugins.

Start with Google Drive for file discovery and file lifecycle tasks, then route to narrower sibling skills only when the task becomes specific to Docs, Sheets, or Slides.

## Workflow

1. Ground the target file first.
- If the user did not provide an exact file URL or ID, use Google Drive search, recent files, folder listing, or metadata reads to identify the right file.
- If the request starts as "find X and then update it," do the Drive discovery step first instead of guessing the target.

2. Stay in the base Google Drive workflow for Drive-native tasks.
- Use the base workflow for search, fetch, recent files, folders, sharing, copying, deleting, exporting, revision history, file moves, and other file-lifecycle work that is not primarily about editing Docs, Sheets, or Slides content.
- For version-history requests, including "previous version," "revision history," "what changed since the last version," or "compare to the prior revision," ground the file, fetch the current content, use `list_file_revisions`, fetch the immediately previous revision or the user-named revision with `fetch_file_revision`, then compare the fetched revision against the current content. Do not say previous versions are unsupported until you have checked whether revision tools are available for the target file.
- For file move requests, ground the source file and target folder, read the file metadata including its current parents, then use `update_file` with `addParents` for the target folder and `removeParents` for only the verified source parent or parents that should no longer contain it. Preserve unrelated parents, and verify the move by reading metadata or listing the target folder before the final response.
- Before any export or raw-file fetch, read or reuse Drive metadata so the MIME type and Google Drive URL are known. Use `export_file` only to convert a native Google Doc, Sheet, or Slide into an explicitly requested format; it returns an authenticated file reference, not inline bytes or base64. Google limits `files.export` responses to **10 MB**; oversized exports fail rather than returning truncated content. For a larger native PDF, use `download_file(id=file_id, mime_type="application/pdf")` when the streaming action is available. It calls Google's `files.download` API and returns a top-level materializable `file_uri`. Once `download_file` is unavailable and canonical `fetch` uses that streamed download path, use `fetch(url=google_drive_url, download_raw_file=True, raw_export_mime_type="application/pdf")` instead. A native-file `fetch` that still uses `files.export` cannot bypass the 10 MB limit. For PDFs, images, ZIPs, Office files, recordings, and other stored, non-native files, use `fetch(url=google_drive_url, download_raw_file=True)`. Use only the authenticated top-level `file_uri` or materialized `workspace_path`; never request inline base64 unless an existing caller explicitly opts into bounded legacy compatibility. Use `fetch` without `download_raw_file` for bounded, best-effort readable text. Do not retry `export_file` after metadata shows a non-native MIME type.

3. Route to the narrowest sibling skill that matches the file type and job.
- Drive, Docs, Sheets, or Slides comment creation, comment replies, comment resolution, or review-by-comments: use [google-drive-comments](../google-drive-comments/SKILL.md).
- Google Docs net-new creation, content summary, revision planning, prose rewriting, or section edits: use [google-docs](../google-docs/SKILL.md).
- Google Sheets creation, local spreadsheet import, range inspection, table cleanup, data restructuring, formula design or repair, chart creation or repair, or batch updates: use [google-sheets](../google-sheets/SKILL.md).
- Google Slides deck summary, content edits, new deck creation, local presentation import, visual cleanup, structural repair, or template migration: use [google-slides](../google-slides/SKILL.md).

## Routing Rules

- If the request is ambiguous between Drive and a file-type surface, use the artifact itself as the tie-breaker:
  - Doc -> Docs skill
  - Sheet -> Sheets skill
  - 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; it owns the mandatory local `.docx` -> native Google Docs import workflow and the explicit-user-override boundary. Do not create a blank Google Doc directly from this router.
- If the user asks to import a local `.docx` into Google Docs, route to the Docs skill and use its native conversion workflow. 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.
- If the user asks to create a new Google Slides deck, route to the Slides skill; it owns the mandatory local `.pptx` -> native Google Slides import workflow and the explicit-user-override boundary. Do not create a blank Google Slides deck directly from this router.
- If the user asks to import a local `.ppt`, `.pptx`, or `.odp` into Google Slides, route to the Slides skill and use its native conversion workflow. Preserve the source file type only when the user explicitly asks for that.
- If the user asks to export or download an existing Drive file, choose the action from metadata: native Google Docs, Sheets, and Slides files use `export_file` for explicit conversions within Google's **10 MB** limit. For a larger native PDF, prefer the currently available streaming `download_file(id=file_id, mime_type="application/pdf")`; after canonical `fetch` adopts the same streamed download path and `download_file` is removed, use `fetch(url=google_drive_url, download_raw_file=True, raw_export_mime_type="application/pdf")`. Stored, non-native PDFs, images, ZIPs, CSVs, Office files, audio, and video use `fetch(url=google_drive_url, download_raw_file=True)`. Use the returned top-level `file_uri` or its authenticated, materialized `workspace_path`; do not expose inline binary, base64, or a bearer URL. Base64 is available only when an existing compatibility caller explicitly requests the bounded legacy behavior.

## Write Safety

- Preserve the user's existing file organization, sharing state, and target artifact unless the request clearly asks to change them.
- When a task can be satisfied by a file-level Drive operation alone, do not load heavier Docs, Sheets, or Slides skills.
- For write-heavy Sheets or Slides work, read the specialized skill before the first large update so request shapes stay grounded.
- For any file import or explicit direct create that returns a user-facing Google Workspace link, wait for the write action to complete and verify the created file with connector readback or Drive metadata readback before returning the URL. Use only a URL or id observed from the completed connector result or readback; never synthesize or predict the URL.

## Related Skills

- Comments: [google-drive-comments](../google-drive-comments/SKILL.md)
- Docs: [google-docs](../google-docs/SKILL.md)
- Sheets: [google-sheets](../google-sheets/SKILL.md)
- Slides: [google-slides](../google-slides/SKILL.md)

Referenced files: 9

View saved version →

---
name: google-drive-comments
description: Write, reply to, and resolve Google Drive comments on Docs, Sheets, Slides, and Drive files with evidence-backed location context. Use when the user asks to leave comments, review a file with comments, respond to comment threads, or resolve Drive comments.
---

# Google Drive Comments

Use this skill for comment workflows in the unified Google Drive plugin. Drive comments can apply to Docs, Sheets, Slides, and generic Drive files, but API-created comments may appear unanchored in the Google editor UI. Every new top-level comment must therefore include enough surface-specific evidence for the reader to find the target without relying on native UI anchoring.

## Workflow

1. Ground the target file first.
- If the user did not provide an exact file URL or ID, search Drive, list recent files, list folders, or read metadata until the target file is unambiguous.
- Identify whether the file is a Google Doc, Sheet, Slides deck, or generic Drive file before drafting comments.

2. Read the surface that will be commented on.
- For Docs or text-like files, read the document text around each likely target.
- For Sheets, read spreadsheet metadata first, then read the specific sheet tabs and ranges that may receive comments.
- For Slides, read the presentation outline or text first, then read specific slides or thumbnails when visual context is needed.
- Do not guess a target quote, slide number, sheet name, or cell range from memory or search snippets.

3. Draft all intended comment updates before writing.
- Prefer one `bulk_update_file_comments` call for all creates, replies, and resolves in the same user request.
- Keep the batch to the action limit exposed by the tool. If the request needs more comments than the limit, ask before splitting into another batch.
- For replies and resolves, use existing comment IDs from the live comment thread data.

4. Attach surface-specific evidence to every new top-level comment.
- The comment body must explicitly name or quote the target evidence, because the Google editor UI may not show API-created anchors.
- Docs or text-like files: include `quoted_text` with the exact sentence, phrase, heading, or nearby text the comment refers to. Also quote that same text in the comment body when the critique would otherwise say "this sentence" or "this paragraph."
- Sheets: include `sheet_cell_range` with the sheet name and A1 cell or range, such as `Budget!C12` or `Pipeline!A2:D10`. Also name that sheet and range in the comment body, and include `quoted_text` when a displayed value, header, formula, or label would make the target clearer.
- Slides: include `slide_number`. Also name that slide number in the comment body, and include `quoted_text` when commenting on a title, bullet, label, chart text, or other visible slide text.
- Generic Drive files: if no structured surface exists, make the comment content explicitly name the file-level, page-level, timestamp-level, or section-level evidence it refers to.

5. Reject vague comments before sending them.
- Do not create comments that say only "this sentence," "this paragraph," "this slide," "this cell," or similar without the matching evidence field.
- If the model has a useful critique but cannot identify the exact evidence target, either turn it into an explicitly file-level summary comment or omit it and say the target was not specific enough.
- Do not rely on tool fields alone for location context. If the comment body would feel hand-wavy after removing the hidden tool fields, rewrite it before sending.

6. Verify the result.
- After writing, summarize how many comments were created, replied to, or resolved.
- Mention the evidence used for the highest-risk comments, especially any file-level comments that intentionally do not target a specific quote, slide, or cell.

## Limitations

- Do not rely on Drive comment `anchor` data for Google Docs, Sheets, or Slides unless the connector explicitly documents a provider-supported shape for that surface. Drive API-created comments may still display as unanchored in the Google editor UI.
- The evidence fields are the durable location contract for this workflow: exact quoted text for Docs and text-like files, sheet/cell range for Sheets, and slide number plus visible text for Slides.

Referenced files: 1

View saved version →

---
name: google-sheets
description: Analyze and edit connected Google Sheets with range precision. Use when the user wants to create Google Sheets, find a spreadsheet, inspect tabs or ranges, search rows, plan formulas, create or repair charts, clean or restructure tables, write concise summaries, or make explicit cell-range updates.
---

# Google Sheets

Use this skill to keep spreadsheet work grounded in the exact spreadsheet, sheet, range, headers, and formulas that matter.

### Spreadsheets clarification questions

- Ask for new spreadsheets or major rewrites. Skip this for edits/conversions.
- Inspect prompt, conversation history, existing file and relevant references to figure out what questions to ask.
- Questions should cover topic, audience, and purpose and come before planning
- When asking questions, focus on consequential dimensions not stated or clearly implied.
- When the artifact is a new analysis, focus on which definition, metric, or lens should drive conclusions.
- Unresolved reference labels or question marks are user-owned: ask, don't infer.
- Once topic, audience, and purpose are clear, proceed without asking. Choose emphasis, format, length, style, details. Use placeholders for missing facts.

Use `request_user_input` once if available, else ask via a message. Have the best suggestion first. Append `(Recommended)` to its label. Have another good alternative second. Have `Use your judgment` as the third and final option. If the request times out or returns no answer, proceed using your best judgment; do not ask again.

## Purpose Of This File

This file is intentionally minimal and only covers:

1. routing to the right spreadsheet workflow
2. stateful operation and mandatory routing to reference files
3. live-read/search safety for direct connector calls

Detailed editing, formula, chart, upload, live-read/search, and batch-update rules live in `references/`.
Latency is not a constraint for this skill, so always read the relevant reference files before performing the task.
If the user has not provided explicit style direction, read `references/style-profiles.md` and apply the appropriate Google Sheets destination default before authoring workbook formatting.

## Default Routing

1. New Google Sheet from a native Google Sheets reference or template URL: copy the entire source workbook with the Drive file-copy action, then trim or repair the copy. Treat a deep-linked `gid` as the initial view, not copy scope. Duplicate one source sheet only when the user explicitly requests a single-sheet extraction. Do not rebuild through `.xlsx` when chips, validation, formulas, rich links, or formatting matter.
2. Other new Google Sheets creation: Inspect the available skills and plugins for the registered `Spreadsheets` capability. It may be exposed as the `$Spreadsheets` skill, the `@Spreadsheets` plugin, or the plugin URI `plugin://spreadsheets@openai-primary-runtime`. If found, load and follow its instructions.
   - If a system spreadsheet plugin or skill is installed, YOU MUST use it to create a local `.xlsx`. Then import the `.xlsx` into Drive as a native Google Sheets spreadsheet. For table-like option/list/dropdown columns, seed a valid row and add native table `DROPDOWN` columns post-import.
   - If neither skill is installed, create the spreadsheet directly with Google Sheets MCP.
3. Existing Google Sheets edits: use Google Sheets MCP directly.

Do not reference the local `.xlsx` in the final answer. Your final answer includes the Google Spreadsheet link only.

## File Safety

Treat a provided Google Sheet as read-only unless the user explicitly asks to edit that file. When a task uses the Sheet as a reference, template, similar structure, or data source, copy it or create a separate Sheet, then verify the output spreadsheet ID differs before writing.

## 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 fallback path.
Do not let accumulated edge-case guardrails turn a straightforward Sheets task into a long blocker-analysis exercise.

For sheet creation and editing tasks, prefer this sequence when viable:

1. Gather the required source material.
2. Pick the correct default routing.
3. Establish the sheet checklist or sheet plan.
4. Build or edit the sheet.
5. Verify the sheet is clean, complete, native, and scannable per `references/reference-visual-quality.md`.
6. Stop once the verified workflow has succeeded.

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

## Required Read Order (No Skips)

For every route that creates, imports, or edits a Google Sheet, read `references/reference-visual-quality.md` before final verification.

If Default Routing uses native Google Sheets reference-follow creation:
1. Read `references/reference-edit-workflow.md`
2. Read `references/reference-live-read-search-safety.md`
3. Read `references/reference-native-cell-structure.md`
4. Read `references/reference-batch-update-recipes.md`

If Default Routing uses the system spreadsheet plugin or skill like `[@spreadsheets](plugin://spreadsheets@openai-primary-runtime)` or `$Spreadsheets`:
1. Read the plugin/skill, e.g. `[@spreadsheets](plugin://spreadsheets@openai-primary-runtime)`
2. Read `references/reference-import-spreadsheet-to-native-sheets.md`
3. If the new Sheet has explicit or reference-derived option/list/dropdown columns, read `references/reference-batch-update-recipes.md` before the post-import table batch update.

If Default Routing uses connector edit workflow:

1. Read `references/reference-edit-workflow.md`.
2. Before any direct live range read, cell read, or `search_spreadsheet_rows`, read `references/reference-live-read-search-safety.md`.
3. Read every task-specific file from the matrix below.
4. If the task spans multiple categories, read all matching files.
5. If uncertain, read every file in `references/`.

Do not execute content edits until the required references are read in the current turn.

## Final Answer Requirement

Unless Default Routing selected native Google Sheets reference-follow creation, if the registered `Spreadsheets` capability like the `[@spreadsheets](plugin://spreadsheets@openai-primary-runtime)` plugin is available, you MUST use one of them to create a local `.xlsx` and import it to Google Drive with `upload_mode: "native_google_sheets"`.
Even though you created a local `.xlsx`, do not cite the local path in the final answer. The final answer cites only the Google Spreadsheet link.

### Spreadsheets location

Use/create `ChatGPT` at My Drive root. Place new spreadsheets created from scratch or from a template there.
Edit existing spreadsheets in place.

Respect user-specified locations.

## Connector Load Checklist

1. Confirm the exact target Google Sheet URL or spreadsheet id before editing an existing spreadsheet.
2. If the user only gives a title or title keywords, use the connector/app search path to identify candidate spreadsheets before asking for a URL.
3. Resolve and record the spreadsheet id, target sheet names, and `sheetId` values.
4. Read spreadsheet metadata before deeper reads or writes.
5. For direct live range reads, cell reads, or `search_spreadsheet_rows`, use exact visible tab names from metadata, bounded ranges, and the recovery rules in `references/reference-live-read-search-safety.md`. Do not guess `Sheet1`, scan whole grids, or retry oversized row searches.
6. Before each edit pass, identify the exact sheet, range, headers, formulas, and validation constraints being edited through connector reads.
7. Re-read target cells before writing when live values, formulas, formatting, or validation could affect the write.

## Task To Reference Map

| Task area | Required reference file |
| --- | --- |
| Existing spreadsheet edit workflow, grounding, validation-backed cells, output conventions, and write planning | `references/reference-edit-workflow.md` |
| Direct live range reads, cell reads, row searches, tab/range recovery, and oversized search avoidance | `references/reference-live-read-search-safety.md` |
| Adding or inserting rows or columns beside populated data while preserving validation, chips, formulas, and formatting | `references/reference-native-cell-structure.md` |
| Reference/template following from a provided Google Sheet | `references/reference-native-cell-structure.md` |
| Raw Sheets write shapes and example `batch_update` bodies | `references/reference-batch-update-recipes.md` |
| Importing a local spreadsheet and upgrading intended tables to native Sheets tables | `references/reference-import-spreadsheet-to-native-sheets.md` |
| Formula design, repair, rollout, or syntax refresh | `references/reference-formula-patterns.md` |
| Chart creation, repair, chart-spec recall, or repositioning | `references/reference-chart-recipes.md` |
| Unspecified styling for native Google Sheets destinations | `references/style-profiles.md` |

Referenced files: 12

View saved version →

---
name: google-slides
description: Route Google Slides authoring requests and derive a design system from a native template or reference deck. Use this skill when the user provides an existing native Google Slides deck as a template, reference, or prior-period source, or asks to edit, update, repair, restyle, or clean up an existing native Google Slides deck. Use the Presentations skill instead for net-new presentation creation when no existing native Google Slides deck must be followed.
---

# Google Slides

### Presentations clarification questions

- Ask for new presentations or major rewrites. Skip this for edits/conversions.
- Inspect prompt, conversation history, existing file and relevant references to figure out what questions to ask.
- Questions should cover topic, audience, and purpose and come before planning
- When asking questions, focus on consequential dimensions not stated or clearly implied.
- When the artifact is a new analysis, focus on which definition, metric, or lens should drive conclusions.
- Unresolved reference labels or question marks are user-owned: ask, don't infer.
- Once topic, audience, and purpose are clear, proceed without asking. Choose emphasis, format, length, style, details. Use placeholders for missing facts.

Use `request_user_input` once if available, else ask via a message. Have the best suggestion first. Append `(Recommended)` to its label. Have another good alternative second. Have `Use your judgment` as the third and final option. If the request times out or returns no answer, proceed using your best judgment; do not ask again.

## Route the Request

- Use `[@presentations](plugin://presentations@openai-primary-runtime)` to create a net-new presentation when no existing native Google Slides deck is the template or reference.
- Use this skill to create a presentation by following an existing native Google Slides template, reference deck, or prior-period deck.
- Use this skill to edit, update, repair, restyle, or clean up an existing native Google Slides deck.
- If a request combines new content with an existing native Google Slides deck that must be followed, use this skill.
- Do not use this skill to author a blank or from-scratch presentation.

## Parse a Template Deck

If code mode is unavailable in the current Codex environment, reproduce the same read-to-file, parse, and render workflow with the available connector and local tools. Preserve the same artifacts and validation steps; do not skip the workflow merely because code mode cannot be used.

For template or reference following, first use code mode to read the complete template/reference presentation directly into a file. Set `SKILL_DIR` to this skill's absolute directory and `WORKSPACE` to an absolute task workspace, then run this in one `functions.exec` call:

```js
const SKILL_DIR = "<absolute-skill-directory>";
const WORKSPACE = "<absolute-task-workspace>";
const loaded = await tools.exec_command({
  cmd: `/bin/cat -- '${SKILL_DIR}/host/read-template-to-file.mjs'`,
  workdir: SKILL_DIR,
  login: false,
  yield_time_ms: 30000,
  max_output_tokens: 20000,
});
if (loaded.exit_code !== 0) throw new Error("Could not load the template reader");
const { readTemplateToFile } = new Function(
  `${loaded.output.replace(/^\s*export\s+/gm, "")}\nreturn { readTemplateToFile };`,
)();
const result = await readTemplateToFile({
  presentationId: "<presentation-id>",
  outputPath: `${WORKSPACE}/raw-template.json`,
  workspaceRoot: WORKSPACE,
  skillRoot: SKILL_DIR,
  tools,
});
text(JSON.stringify(result));
```

The reader omits the `fields` argument so the connector returns the full presentation resource, then writes the unmodified connector response to `raw-template.json` without placing it in model context.

Next, set `NODE` to the bundled Node.js executable returned by the workspace dependency loader and run:

```bash
"$NODE" "$SKILL_DIR/scripts/parse_template_design_system.mjs" \
  --input "$WORKSPACE/raw-template.json" \
  --output "$WORKSPACE/design-system.json" \
  --catalog "$WORKSPACE/design-catalog.md"
```

`--catalog` is optional. Use the JSON for master families, layout and placeholder IDs, inherited styles, theme colors, protected regions, and exemplar geometry. Use the catalog as a compact planning view. Confirm semantic and visual interpretations against rendered source slides; the parser derives structure but does not render the deck.

## Render a Deck

Export a deck once as PDF and render every slide locally instead of fetching one thumbnail per slide. Set `PDFTOPPM` to `pdftoppm` inside the native-binaries directory returned by the workspace dependency loader, then run this in one `functions.exec` call:

```js
const SKILL_DIR = "<absolute-skill-directory>";
const WORKSPACE = "<absolute-task-workspace>";
const PDFTOPPM = "<absolute-native-binaries-directory>/pdftoppm";
const loaded = await tools.exec_command({
  cmd: `/bin/cat -- '${SKILL_DIR}/host/export-and-render-slides.mjs'`,
  workdir: SKILL_DIR,
  login: false,
  yield_time_ms: 30000,
  max_output_tokens: 30000,
});
if (loaded.exit_code !== 0) throw new Error("Could not load the slide renderer");
const { exportAndRenderSlides } = new Function(
  `${loaded.output.replace(/^\s*export\s+/gm, "")}\nreturn { exportAndRenderSlides };`,
)();
const result = await exportAndRenderSlides({
  presentationId: "<presentation-id>",
  outputDir: `${WORKSPACE}/renders/<deck-name>`,
  workspaceRoot: WORKSPACE,
  skillRoot: SKILL_DIR,
  designSystemPath: `${WORKSPACE}/design-system.json`,
  pdftoppmPath: PDFTOPPM,
  dpi: 120,
  tools,
});
text(JSON.stringify(result));
```

Use the helper as shown instead of calling Drive `fetch` or `export_file` directly. It automatically handles current reference-backed and legacy inline responses, writes `presentation.pdf`, and returns ordered PNGs mapped to native slide IDs. It fails if the PDF page count differs from the design system. Use a fresh output directory, then inspect every PNG with `view_image`; create a local contact sheet when useful.

### Presentations location

Use/create `ChatGPT` at My Drive root. Place new presentations created from scratch or from a template there.
Edit existing presentations in place.

Respect user-specified locations.

## Build From the Template

For template or reference following, copy the template once and edit only the copy.

Before making mutations, use the design catalog and rendered template slides to choose and record for every planned output slide:

- its narrative role;
- the native template exemplar slide ID or layout ID;
- whether it will be built by duplicating the exemplar or creating from the layout.

Match exemplars by narrative role, content density, evidence type, orientation, hierarchy, and meaning-bearing slots—not merely by object count or visual similarity. If the user links a particular template slide, inspect it explicitly and use it when it fits the requested role.

Do not use an exemplar containing device mockups, photography, screenshots, charts, or other meaning-bearing slide-local media unless every such element is explicitly mapped to destination content as keep, replace, or delete. If every element cannot be mapped, choose another exemplar.

Treat template placeholder media as meaning-bearing slide-local media. Explicitly map every image and video slot in a selected exemplar—especially speaker portraits—to keep, replace, or delete; never leave an unmapped placeholder in the output.

Prefer these construction methods in order:

1. Duplicate a rendered template exemplar when its design depends on slide-local shapes, image or chart frames, tables, groups, video, custom text styles, footer treatment, or other native objects.
2. Create from an inspected template layout only when its inherited placeholders are sufficient.
3. Populate, replace, or remove existing exemplar objects and inherited placeholders before creating new primary text, image, table, chart, or shape objects.
4. Create a new composition only when no inspected exemplar or layout can support the content; keep it consistent with the nearest template family.

Treat slide-local structure as part of the template. When a duplicated exemplar already contains a table, title frame, card structure, divider, footer, image frame, or other reusable structural object, edit it in place. Do not delete and recreate it merely to simplify implementation. Remove an object only after explicitly mapping it to `delete` because the destination slide does not need it.

Preserve the intrinsic aspect ratio of every image and video. Never stretch media by independently setting its width and height or by applying unequal horizontal and vertical scaling without deriving both from its intrinsic dimensions. Do not blindly reuse an exemplar media transform when the replacement has a different aspect ratio.

Use crop-to-fill only for decorative photography or full-bleed imagery where edge cropping is safe. Fit screenshots, charts, diagrams, UI, and videos fully within the intended frame so all meaning-bearing content remains visible; center the result, and prefer empty margins to distortion or loss of important content. Treat stretched media or improperly cropped meaning-bearing content as a concrete visual defect.

Preserve each exemplar's font family, weighted font family, font size, bold and italic state, color, paragraph styling, geometry, and object type by default. Change one of these only to resolve a concrete content-fit defect.

Preserve the template's font sizes whenever possible. If text overflows, first consider a small, local font-size reduction; do not shrink an entire mixed-style text box to solve one overflowing passage. Never reduce narrative body or list text below 12 pt. If the template already defines smaller narrative text for the same role, preserve that template size but do not reduce it further. Template-native captions, footers, source notes, and micro-labels may remain smaller, but do not reuse those smaller styles for narrative content.

If content still does not fit readably, choose a denser suitable exemplar or shorten flexible wording while preserving the original meaning, tone, facts, and required details. Treat reaching the 12 pt narrative floor, visible overcrowding, conspicuously undersized text, or leaving a major intended region unused as evidence that the archetype is wrong—not as a cue for further local typography repairs. Restore the template size and switch to a more appropriate exemplar or shorten the copy; do not apply a uniform minimum-size style to an entire text box or keep adjusting paragraphs to force an unsuitable exemplar. If adapting an image-led exemplar requires deleting its principal media slot and leaving that region empty, choose a text-first exemplar instead.

Treat multiple text and paragraph styles within one text box as structural. If a text box combines a title, kicker, label, body, or other differently styled runs, replace the corresponding text while preserving the existing run and paragraph styles. Do not apply one uniform style to the entire text box.

Before replacing text in a mixed-style text box, record its existing text and paragraph runs and update the corresponding ranges. Do not use `deleteText` over `ALL` followed by `insertText` and `updateTextStyle` over `ALL`; if replacement changes run lengths, reconstruct the original styled ranges explicitly.

Use native paragraph bullets for lists. Never type leading hyphens or visible bullet glyphs such as `•`, `◦`, `▪`, or `‣` into inserted text to imitate a bulleted list. When an exemplar uses a custom bullet character or style, preserve its existing list formatting and edit the paragraph text without replacing or normalizing the marker.

Every bulleted paragraph must contain visible text. Never leave an empty or whitespace-only bulleted paragraph. When an exemplar contains more list items than needed, delete the unused paragraph or remove its bullet formatting; use paragraph spacing instead of a blank bullet to create vertical separation.

Do not create from a blank layout when an inspected rich exemplar can support the narrative role and evidence type.

Use one consistent exemplar or layout family for truly recurring slide roles. This does not mean collapsing visually distinct section-title, speaker, agenda, or content archetypes into one generic construction. If content does not fit, shorten flexible wording or choose a better-fitting template archetype; do not flatten the template's typography or redesign a sparse composition into a dense canvas.

Preserve native links, notes, tables, charts, and media types when supported, and remove stale exemplar content. Keep unused template-library slides until the delivered slides and final order are verified, then delete them last.

Do not rasterize editable source narrative text merely to preserve its appearance. Recreate it as native Google Slides text using the template's typography and hierarchy. Text may remain rasterized only when it is intrinsically part of a required screenshot or other source media asset.

## Work Efficiently

Read, parse, and render each unchanged template or content source only once. Reuse the local design system, catalog, PDF, and rendered images.

Complete all planned slide construction and content population before output visual QA. Confirm the delivered slide IDs through one live structural readback, then remove unused template-library slides and establish the final order before the first output PDF render.

Read and parse the output once after its final slide set and order are established. Reuse that output design system after text, style, image, or media repairs. Parse it again only when a structural mutation changes slide IDs, slide count, or slide order.

Before the first output PDF render, run the local issue checker on the raw presentation JSON already saved by that structural readback:

```bash
"$NODE" "$SKILL_DIR/scripts/check_output_issues.mjs" \
  --input "$WORKSPACE/raw-output.json" \
  --output "$WORKSPACE/output-issues.json"
```

The checker makes no API or render calls. It reports only compact, object-level findings for empty native bullet paragraphs, duplicate or typed bullet markers, explicitly undersized narrative text, unresolved generic placeholder text, empty text placeholders, and structurally blank slides. Repair every `error` before rendering. Treat `warning` findings as review prompts and preserve intentional template-native exceptions. Combine applicable repairs with the existing consolidated repair pass; do not add a read, parse, render, or diagnostic-rerun cycle solely to clear warnings.

Inspect every delivered slide from one output render and collect all concrete defects before repairing. Prefer one consolidated repair pass, but perform a second consolidated pass when defects remain. A structural rebuild invalidates prior visual QA: render the complete delivered deck again and use the second repair pass if needed. Do not perform more than two repair passes. Do not create additional read, parse, or render cycles without a concrete defect or structural change that invalidates an existing artifact.

Complete duplication and slide creation before reordering. Reorder in a separate mutation after structural readback, using each delivered slide ID exactly once.

Referenced files: 15