documents

Files (76)

• LICENSE.txt
• SKILL.md
• openai.yaml · agents/
• file-document.png · assets/
• end_to_end_smoke_test.md · examples/
• manifest.txt
• comments.md · ooxml/
• hyperlinks_and_fields.md · ooxml/
• rels_and_content_types.md · ooxml/
• tracked_changes.md · ooxml/
• design_presets.md · references/
• header_templates.md · references/
• render_docx.py
• a11y_audit.py · scripts/
• accept_tracked_changes.py · scripts/
• add_tracked_replacements.py · scripts/
• apply_template_styles.py · scripts/
• captions_and_crossrefs.py · scripts/
• comments_add.py · scripts/
• comments_apply_patch.py · scripts/
• comments_extract.py · scripts/
• comments_strip.py · scripts/
• content_controls.py · scripts/
• docx_ooxml_patch.py · scripts/
• docx_table_to_csv.py · scripts/
• fields_materialize.py · scripts/
• fields_report.py · scripts/
• flatten_ref_fields.py · scripts/
• footnotes_report.py · scripts/
• google_docs_title_sanitize.py · scripts/
• heading_audit.py · scripts/
• images_audit.py · scripts/
• insert_note.py · scripts/
• insert_ref_fields.py · scripts/
• insert_toc.py · scripts/
• internal_nav.py · scripts/
• make_fixtures.py · scripts/
• merge_docx_append.py · scripts/
• privacy_scrub.py · scripts/
• redact_docx.py · scripts/
• render_and_diff.py · scripts/
• section_audit.py · scripts/
• set_protection.py · scripts/
• style_lint.py · scripts/
• style_normalize.py · scripts/
• table_geometry.py · scripts/
• watermark_add.py · scripts/
• watermark_audit_remove.py · scripts/
• xlsx_to_docx_table.py · scripts/
• accessibility_a11y.md · tasks/
• captions_crossrefs.md · tasks/
• clean_tracked_changes.md · tasks/
• comments_manage.md · tasks/
• compare_diff.md · tasks/
• create_edit.md · tasks/
• fields_update.md · tasks/
• fixtures_edge_cases.md · tasks/
• footnotes_endnotes.md · tasks/
• forms_content_controls.md · tasks/
• headings_numbering.md · tasks/
• …and 16 more

SKILL.md (first lines)

# Documents Skill (Read • Create • Edit • Redline • Comment)

Use this skill when you need to create or modify `.docx`, Word, or Google
Docs-targeted document artifacts **in this container environment** and verify
them visually.

## Tools + Contract

- Use the workspace dependencies bundled codex primary runtime (`$CODEX_PRIMARY_RUNTIME`) for docx artifact work. Python/Node runtimes are `$CODEX_PRIMARY_RUNTIME_PYTHON` and `$CODEX_PRIMARY_RUNTIME_NODE`. Do not use system `node`, system `python`, global npm packages, or repo-local installs.
- For document creation and deterministic OOXML edits, it is still acceptable to use the bundled Python/OOXML helper scripts in this skill package when the JS surface is incomplete.
- Run any builder or helper file from a writable workspace or temp directory, not from the managed dependency directory itself.
- Final user-facing responses should describe only the requested document result
  and link only to the final `.docx`, Word, or Google Docs deliverable unless
  the user explicitly asks for QA intermediates.

## Google Docs-targeted output

For a net-new Google Docs request, create and visually verify a local `.docx` with this skill first. The native Google Docs deliverable must then be produced by the Google Drive plugin's document import action, `mcp__codex_apps__google_drive_import_document`, with `upload_mode: "native_google_docs"`.

Before rendering or importing any Google Docs-targeted DOCX, run the deterministic title sanitizer:

```bash
python scripts/google_docs_title_sanitize.py input.docx --out sanitized.docx
python scripts/google_docs_title_sanitize.py sanitized.docx --check
```

Use the sanitized DOCX for render QA and native Google Docs import. This is not a style preference or prose reminder: the sanitizer removes Word `Title` paragraph-style border residue, direct title-paragraph borders, and leading title-block paragraph borders from the OOXML so Word's built-in blue title rule cannot survive into the imported Google Doc.

Do not use Computer Use, Browser Use, blank-Google-Doc creation plus Google Docs write APIs, or another direct-to-Docs construction path for net-new Google Docs unless the user explicitly asks for that alternate workflow. If they do, mention first that output quality is expected to be best when a local `.docx` is imported through the Google Drive plugin.

If the Google Drive plugin is unavailable, use the plugin-install/user-elicitation flow to ask the user to install `google-drive@openai-curated`. If the plugin is available but `_import_document` is missing, ask the user to reinstall or refresh the Google Drive plugin before continuing with the native Google Docs deliverable.

## Non-negotiable: render → inspect PNGs → iterate

**You do not “know” a DOCX is satisfactory until you’ve rendered it and visually inspected page images.**
DOCX text extraction (or reading XML) will miss layout defects: clipping, overlap, missing glyphs, broken tables, spacing drift, and header/footer issues.

**Shipping gate:** before delivering any DOCX, you must:

- Run `render_docx.py` to produce `page-<N>.png` images (optionally also a PDF with `--emit_pdf`)
- Open the PNGs (100% zoom) and confirm every page is clean
- If anything looks off, fix the DOCX and **re-render** (repeat until flawless)

If rendering fails because LibreOffice/`soffice` is missing, it is acceptable to return the requested DOCX without rendered PNG QA. In that fallback case, use the relevant Markdown task docs in this skill package as the authoritative guidance for building and checking the document structurally, state clearly in the final response that rendering/visual QA could not be completed, and do not imply that the document passed the render gate.

If rendering fails for any other reason, fix rendering first (LibreOffice profile/HOME, conversion errors, or renderer setup) rather than guessing.

**Deliverable discipline:** Rendered artifacts (PNGs and optional PDFs) are for internal QA only. Unless the user explicitly asks for intermediates, **return only the requested final deliverable** (e.g., when the task asks for a DOCX, deliver the DOCX — not page images or PDFs).

## Design Preset Contract

For new DOCX creation and major rewrites, a design preset is mandatory unless the user explicitly asks for a different visual system. For existing-document edit tasks, preserve the original document and apply the minimal local edits described later in this skill.

Picking a preset is not enough. You must resolve the preset into exact numeric tokens and apply those numbers in the DOCX implementation. Do not rely on Word defaults, built-in list styles, theme defaults, inherited paragraph spacing, or renderer-dependent behavior for any preset-controlled value.

Before writing content, read `references/design_presets.md` and choose exactly one preset:

- `google_docs_default` for any net-new document whose destination is a native Google Doc, unless the user explicitly asks for a special, branded, or highly polished visual treatment.
- `standard_business_brief` for formal memos, RFI responses, decision memos, and board-style briefs.
- `compact_reference_guide` for launch guides, negotiation briefs, checklists, and dense operator references.
- `narrative_proposal` for grants, proposals, and persuasive documents with longer prose.
- Use an archetype alias from the reference file when it is a closer match: `rfi_response`, `decision_memo`, `launch_messaging_guide`, `contract_negotiation_brief`, `neighborhood_business_proposal`, or `grant_proposal`.

If the destination is Google Docs, choose `google_docs_default`. Google Docs-targeted documents should feel native: Arial-based typography, black hierarchy, simple title treatment.

For Google Docs-targeted documents, never create the title with the built-in Word `Title` paragraph style, including `doc.add_paragraph(..., style="Title")` or `doc.add_paragraph(style="Title")`. Always create a plain paragraph and apply the selected style-sheet title tokens directly: font family, size, color, weight, spacing, and border/rule settings. For `google_docs_default`, that means Arial 26 pt, black, normal weight, 0 pt before, 3 pt after, and no underline, bottom border, horizontal rule, or other Word-template residue. This instruction is not the enforcement layer; `scripts/google_docs_title_sanitize.py` is the deterministic enforcement layer and must still run before render/import.

If creating a new first-page header, cover, or title block for a non-Google-docs document, also read `references/header_templates.md` and choose one header pattern before drafting. For `google_docs_default`, keep the opening block simple unless the user explicitly requests richer first-page furniture.

Then resolve the preset into a token map and apply the tokens consistently:

1. Set page, margin, type scale, paragraph rhythm, heading, list, table, callout, header, footer, and color tokens before drafting. For `google_docs_default`, that means explicitly carrying the simple Google Docs defaults instead of inheriting the more polished Word-oriented defaults above.
2. Implement those tokens through Word styles, real numbering definitions, explicit table geometry, and header/footer parts. Do not fake headings, lists, or tables with one-off direct formatting.
3. Use ad-hoc formatting only when the document needs a specific exception; record the exception as a named override and reuse it consistently wherever that role appears.
4. Keep the preset stable throughout the document. Do not mix body spacing, heading colors, list indents, table fills, or page furniture from multiple presets.

Baseline geometry for all presets: US Letter portrait, 1 inch margins, 9360 DXA usable width, real Word styles for Normal/Title/Subtitle/Heading 1/Heading 2/Heading 3, real Word numbering for lists, and DXA table widths only.

Tables must use explicit Word geometry. Build rows first, compute exact DXA column widths, then use `scripts/table_geometry.py` or equivalent logic so `tblW`, `tblInd`, `tblGrid`, and every `tcW` agree. Set table indent to the start cell margin token (`120` DXA by default) so the visible outer border aligns with surrounding paragraph text. Do not rely on autofit, percentage widths, centered default tables, fixed row heights, or tables as layout/divider hacks.

Lists must use real numbering definitions. Never create fake bullets with Unicode bullet text, hyphen-prefixed paragraphs, manual numbers, or newline-separated list items inside one paragraph. Wrapped list lines must align under the item text, not under the marker.

Before final render review, run a preset audit: page geometry, styles, heading spacing/colors, list indents, table widths/table indents/cell margins, callout fills, headers/footers, and direct-formatting exceptions must match the selected token map. Also check for fake headings, fake bullets, missing table geometry, clipped/pinned table text, inconsistent page furniture, and unexplained direct formatting drift. For `google_docs_default`, fail the audit if the title style or title paragraph contains `w:pBdr`, a bottom border, an underline, a horizontal rule, or any rendered decorative line under the title.

## Form factor selection

For new DOCX creation and major rewrites, choose content form factors deliberately before drafting. Start from the information type, then calibrate the structure to the document archetype. Use the lightest readable structure that helps the reader understand, compare, act on, or fill in the information with the least friction.

First map each major content unit to a form factor:

- PROSE SECTION: narrative, explanation, background, or rationale. Use paragraphs under clear headings, with short supporting bullets only when they improve skimming.
- LEAD CALLOUT: decision, recommendation, or key takeaway. Use a short labeled paragraph, callout, or lead paragraph followed by concise rationale.
- NUMBERED STEPS: sequence, workflow, or procedure. Use step blocks with clear action verbs; add owner/status fields only when they are central to execution.
- GROUPED BULLETS: loose factors, considerations, pros/cons, or requirements. Use bullets or short subsections when order is not the main point.
- CHECKLIST: actions, acceptance checks, or review criteria. Use compact labels and enough spacing to scan.
- NOTE BOX: warnings, caveats, constraints, or important notes. Use a callout with restrained emphasis.
- DEFINITION LIST: definitions, metadata, or key facts. Use labeled paragraphs, definition lists, or compact key-value blocks.
- TABLE: repeated comparable records, status grids, budgets, RFI/compliance matrices, or schedules with shared fields.
- FORM LAYOUT: forms and questionnaires. Use readable fields, sectioning, and response space; use grids only where repeated response structure helps completion.
- SOURCE LIST: evidence, citations, and sources. Use footnotes, endnotes, short source lists, or appendices according to document type and density.

### Table Gate

Use a table only when the content is truly row/column data: repeated items, shared fields, and useful comparison or lookup.

Do not use tables to package normal prose. If cells become mini-paragraphs, switch to prose sections, bullets, steps, checklists, callouts, or appendix material.

Before finalizing, run a table-overuse audit:

- If most cells in a table are sentence- or paragraph-length prose, convert that section to prose, bullets, steps, callouts, or labeled paragraphs.
- If two or more adjacent sections use tables, check whether at least one should become bullets or paragraphs for readability.

During render review, check content diversity and archetype fit. If multiple adjacent components use the same visual form, decide whether one should become prose, bullets, steps, a callout, or an appendix. The goal is not variety for its own sake; it is to match form to reading task and document purpose.

## Design standards for document generation

For generating new documents or major rewrite/repackages, follow the design standards below unless the user explicitly requests otherwise. The user's instructions always take precedence; otherwise, adhere to these standards.

When creating the document design, do not compromise on the content and make factual/technical errors. Do not produce something that looks polished but not actually what the user requested.

From lightspeedwp/.github, GPL-3.0.

More from lightspeedwp/.github