Google Drive

View saved version →

---
name: google-docs
description: Create and edit native Google Docs through connected tools.
---

# Google Docs

Create and edit native Google Docs through connector tools, which handle authentication. For content edits, `batch_update_document` calls Google’s `documents.batchUpdate` API. Verify connector capabilities before claiming a feature is unsupported.

## Choose the route

- **New document:** create a native Google Doc with the Drive create action and `application/vnd.google-apps.document`.
- **Edit an existing document:** edit the specified document in place. Read the target and surrounding structure with the Google Docs tools before writing. For large responses or complex native controls, optionally use the [file-backed read helper](references/reference-trusted-read-wrapper.md) to save a searchable outline and control inventory. Do not write through an opaque control range you cannot inspect.
- **Use a template:** when creating a new document from a template, copy it natively to preserve its formatting and embedded features. When adapting a past document, update task-relevant content across every retained tab; preserving structure does not mean carrying forward old people, dates, links, or approvals. Edit an existing document in place when that is what the user requests.
- **Convert Word to Google Docs:** only when the user supplies a Word file and asks to convert it. Call `mcp__codex_apps__google_drive_import_document` with `source_file` set to its absolute local path, the desired `title`, and `upload_mode: "native_google_docs"`. Preserve the source file. Verify the response identifies a native Google Doc (`application/vnd.google-apps.document`) and supplies its ID or URL, then read it back to check content, headings, lists, tables, and embedded elements against the source. When layout fidelity matters, compare an exported PDF with the source rendering. Repair conversion drift with scoped edits that preserve the source formatting, and report any remaining fidelity loss.

Place new documents and template copies in `ChatGPT` at My Drive root unless the user specifies another location. Edit existing documents in place.

## Edit without losing structure

`batch_update_document` applies direct edits, not tracked suggestions.

1. Resolve the destination document ID, target `tabId`, and current structure. A URL pointing at one tab does not describe the whole document. Inspect all tabs when copying or editing the whole document; a targeted edit needs only its relevant scope.
2. Resolve paragraph, table-cell, and native-element ranges from connector readback. Docs indexes are UTF-16 code units, not character counts. Requests in a batch execute sequentially, so earlier inserts and deletions change later indexes.
3. Batch compatible edits in one `batch_update_document` call, accounting for sequential index shifts. Combine text insertion and its formatting when ranges can be calculated from the inserted text. Make scoped edits. Do not rebuild a document for a small correction or replace a table/control with its visible text. Match nearby peer styles when adding content to an existing structure.
4. Use `write_control.requiredRevisionId` for edits that should fail on concurrent changes. Use a returned revision for the next guarded batch when available. Read again only when a later edit needs positions or native IDs you cannot reliably derive, a revision conflict occurs, or a write outcome is uncertain; reconcile that outcome before retrying. Do not read after every tool call.
5. After the planned edits, read back the changed area once to verify content, location, native element types, and preservation of nearby structure. Use PDF rendering when page fit or image placement matters; connector metadata alone cannot prove rendered layout. Export and inspect the relevant PDF pages for that check; HTML and thumbnails do not prove page fit.

### Formatting and native features

For new documents, use Google Docs’ supplied named styles, fonts, spacing, and margins unless the user requests a different design. Use `TITLE` for a visible title, `HEADING_1` for main sections, and `HEADING_2` for subsections; keep peer sections at the same level. For existing documents and template copies, preserve their formatting and match nearby peers when adding content.

Use named paragraph styles for headings and native list requests for lists. Set only `namedStyleType` for a heading unless the user requests overrides or a sampled peer requires them. Changing a paragraph to `NORMAL_TEXT` may leave explicit character formatting intact; reset unintended inherited styling on inserted body text to match its intended body style.

Smart chips are optional unless requested or needed to match an existing field. Preserve chips, links, and controls outside the edit scope rather than converting them globally.

### Dropdowns

Preserve dropdowns when editing nearby content. To create or update them, pass dropdown request objects to the connector's `batch_update_document` tool; see the [dropdown example and readback checks](references/reference-smart-chips-and-building-blocks.md#dropdowns).

## References: read as needed

| When to read | Reference |
| --- | --- |
| Composing requests for text, formatting, lists, tables, hyperlinks, or images | [Connector examples](references/reference-direct-request-composition.md) |
| Working with smart chips, dropdowns, or existing building blocks | [Smart chips, dropdowns, and building blocks](references/reference-smart-chips-and-building-blocks.md) |
| Creating Calendar-backed meeting notes using a complete request example | [Meeting-notes example](references/reference-meeting-notes-direct.md) |
| Using the optional helper to inspect a large or complex document response | [File-backed read helper](references/reference-trusted-read-wrapper.md) |

## Output delivery

These citation directives are only for the final chat response to the user. Never insert them into the Google Doc. For source references inside the document, use ordinary hyperlinks or the citation style requested by the user.

- **`purpose="output"`:** use for each final Google Doc created or edited for the user. Cite it exactly once, on its own line in its own paragraph, outside prose and list items. Briefly describe the result separately without repeating its filename, path, or link. Do not use output citations for unchanged files or read-only answers.
- **`purpose="source"`:** use for each document whose contents you summarize or use to support an answer. Place the citation inline where the document is referenced, in place of its filename. Do not write the filename separately and append its citation. Files merely inspected but not used in the answer need no citation.
- Include only `path` and `purpose` inside each directive. Do not add a description, title, label, `mode`, or other attributes. Any explanatory prose belongs outside the directive.
- Emit `:codex-file-citation{...}` directly, without backticks, code fences, or a Markdown-link wrapper. Use verified targets only. No need to cite or reference intermediate work.

Set `path` to the verified native Google Docs URL returned by the connector. Citation directives are exempt from “Return web URLs as Markdown links.”

Examples below use placeholders; actual responses use verified URLs and no code fences.

```text
:codex-file-citation{path="https://docs.google.com/document/d/<verified-file-id>" purpose="output"}
```

```text
The review of :codex-file-citation{path="https://docs.google.com/document/d/<verified-file-id>" purpose="source"} is due Friday.
```

Referenced files: 23

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.

## Purpose Of This File

This file 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
4. final-response citations and delivery

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.

Deliver the verified native Google Sheet. Never include the local `.xlsx` unless explicitly asked for by the user.

## 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/`.

## 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"`.

### Final Response Citations

- **Create/edit:** for created or edited spreadsheets, cite each final deliverable exactly once with `purpose="output"`, in its own paragraph. Briefly describe the result without repeating its filename, path, or link. Never put output directives inside prose or list items.
- **Q&A and summaries:** Every file whose contents you summarize or use to support an answer MUST receive a `:codex-file-citation{...}` with `purpose="source"` in the final response. Use the source citation in place of the filename, wherever the filename would appear. Do not write the filename separately and append its citation at the end. Files merely inspected but not used in the answer need no citation. Do not emit output citations for unchanged files or read-only answers.

- Emit `:codex-file-citation{...}` directly, without backticks, code fences, or a Markdown-link wrapper. Use verified targets only. No need to cite or reference intermediate work.

Deliver a native Google Sheets file even when another authoring workflow was used to build it, unless the user explicitly requests preservation of the source file type or no conversion. Set `path` to its verified native URL returned by the connector and omit `mode`. Citation directives are exempt from “Return web URLs as Markdown links.”

Some illustrative examples, real responses use verified targets outside code fences.

```text
:codex-file-citation{path="https://docs.google.com/spreadsheets/d/<verified-file-id>" purpose="output"}
```

```text
The review of :codex-file-citation{path="https://docs.google.com/spreadsheets/d/<verified-file-id>" purpose="source"} is due Friday.
```

### 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

## 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.

## Output Format

### Final Response Citations

- **Create/edit:** for created or edited presentations, cite each final deliverable exactly once with `purpose="output"`, in its own paragraph. Briefly describe the result without repeating its filename, path, or link. Never put output directives inside prose or list items.
- **Q&A and summaries:** Every file whose contents you summarize or use to support an answer MUST receive a `:codex-file-citation{...}` with `purpose="source"` in the final response. Use the source citation in place of the filename, wherever the filename would appear. Do not write the filename separately and append its citation at the end. Files merely inspected but not used in the answer need no citation. Do not emit output citations for unchanged files or read-only answers.

- Emit `:codex-file-citation{...}` directly, without backticks, code fences, or a Markdown-link wrapper. Use verified targets only. No need to cite or reference intermediate work.

Deliver a native Google Slides file even when another authoring workflow was used to build it, unless the user explicitly requests preservation of the source file type or no conversion. Set `path` to its verified native URL returned by the connector and omit `mode`. Citation directives are exempt from “Return web URLs as Markdown links.”

Some illustrative examples, real responses use verified targets outside code fences.

```text
:codex-file-citation{path="https://docs.google.com/presentation/d/<verified-file-id>" purpose="output"}
```

```text
The review of :codex-file-citation{path="https://docs.google.com/presentation/d/<verified-file-id>" purpose="source"} is due Friday.
```

Referenced files: 15