docx

# DOCX Skill Use this skill when a task involves a Word `.docx` document and correctness depends on document structure, formatting, tracked changes, comments, fields, tables, forms, or rendered layout. ## Core workflow 1. Identify the operation: read/review, create/edit, template following, redlining/comments, conversion, or final verification. 2. Keep the source document unchanged for review and template-distillation work. Write outputs and intermediate files to a task-specific writable directory. 3. Use `Node OOXML` for ordinary paragraphs, runs, styles, tables, headers/footers, and page setup. Use the bundled helpers under `scripts/` for deterministic audits and OOXML operations. 4. After every meaningful create or edit batch, render the document with `render_docx.mjs`, inspect every generated page image, and iterate until the layout is clean. 5. Deliver only the requested final document. Keep rendered PNGs, temporary PDFs, audit JSON, and diff images as internal QA artifacts unless requested. ## Route to the relevant guide Read only the supporting guide needed for the current operation: - Existing-document reading or review: [references/tasks/read_review.md](references/tasks/read_review.md) - Creating or editing a document: [references/tasks/create_edit.md](references/tasks/create_edit.md) - Render and visual verification: [references/tasks/verify_render.md](references/tasks/verify_render.md) - Accessibility and document structure: [references/tasks/accessibility_a11y.md](references/tasks/accessibility_a11y.md) - Styles and formatting cleanup: [references/tasks/style_lint_normalize.md](references/tasks/style_lint_normalize.md) - Templates and style packs: [references/tasks/templates_style_packs.md](references/tasks/templates_style_packs.md) - Template distillation and creation: [references/template-distill.md](references/template-distill.md) and [references/template-create.md](references/template-create.md) - Tables and spreadsheet-to-document conversion: [references/tasks/tables_spreadsheets.md](references/tasks/tables_spreadsheets.md) - Forms/content controls: [references/tasks/forms_content_controls.md](references/tasks/forms_content_controls.md) - Captions and cross-references: [references/tasks/captions_crossrefs.md](references/tasks/captions_crossrefs.md) - Fields and field display text: [references/tasks/fields_update.md](references/tasks/fields_update.md) - Navigation and table of contents: [references/tasks/navigation_internal_links.md](references/tasks/navigation_internal_links.md) and [references/tasks/toc_workflow.md](references/tasks/toc_workflow.md) - Tracked changes: [references/tasks/clean_tracked_changes.md](references/tasks/clean_tracked_changes.md) and [references/ooxml/tracked_changes.md](references/ooxml/tracked_changes.md) - Comments: [references/tasks/comments_manage.md](references/tasks/comments_manage.md) and [references/ooxml/comments.md](references/ooxml/comments.md) - Hyperlinks, fields, headers, and page numbers: [references/ooxml/hyperlinks_and_fields.md](references/ooxml/hyperlinks_and_fields.md) - Package relationships and content types: [references/ooxml/rels_and_content_types.md](references/ooxml/rels_and_content_types.md) - Redaction, privacy, protection, watermarks, footnotes, merging, or sections: use the matching file under `references/tasks/`. ## Rendering and visual QA The canonical renderer converts DOCX to PDF internally and rasterizes each page to `page-<N>.png`: ```bash node scripts/render_docx.mjs input.docx --output_dir /path/to/qa ``` Use `--emit_pdf` only when an intermediate PDF is useful for diagnosis. Use `--verbose` when LibreOffice conversion needs debugging. Inspect every page at full resolution for clipped or overlapping text, missing glyphs, broken tables, unexpected page breaks, and header/footer drift. Text extraction or XML checks alone cannot prove visual correctness. If LibreOffice is unavailable, complete structural checks with the relevant audits and state that visual QA could not be performed. If conversion fails for another reason, diagnose the renderer/profile problem before judging the DOCX. For repeated comparisons, use `scripts/render_and_diff.mjs`. For a quick structural pass, use the audits for sections, headings, images, fields, footnotes, comments, tables, styles, watermarks, accessibility, or content controls as applicable. ## New documents and major rewrites When no supplied template controls the design, choose exactly one preset from [references/design_presets.md](references/design_presets.md): - `standard_business_brief` for formal memos and executive briefs - `compact_reference_guide` for checklists, launch guides, and dense references - `narrative_proposal` for proposals and longer persuasive documents - an archetype alias defined by the reference when it is a closer fit Resolve the preset into explicit page, margin, typography, spacing, list, table, color, header, and footer tokens before drafting. Use real Word styles, numbering definitions, and fixed DXA table geometry; do not depend on inherited defaults or visual approximations. Read [references/header_templates.md](references/header_templates.md) when a new first-page header, cover, or title block is needed. Use the lightest form factor that matches the content: prose for explanation, bullets for unordered considerations, numbered steps for procedures, checklists for acceptance criteria, callouts for warnings, and tables only for genuinely tabular data. Avoid using tables as layout containers or turning cells into long prose blocks. ## Editing, redlining, and OOXML For an existing document, preserve the original structure and make the smallest local change that satisfies the request. Do not rewrite unrelated paragraphs or styles. Real tracked changes and Word comments require OOXML patching; use the corresponding helpers and perform another render plus structural check after any package-level change. Use `scripts/privacy_scrub.mjs` before publication when personal metadata or `rsid` values should be removed. Use `scripts/redact_docx.mjs` for explicit redaction/anonymization requests and verify the result structurally and visually. Use `scripts/set_protection.mjs` only when the requested output needs editing restrictions. ## File and command conventions - Refer to inputs and outputs by absolute paths when reporting results. - Keep temporary work in a unique writable directory; never modify a retained reference document during inspection. - Prefer the bundled Node/MJS helpers and the renderer bundled with the application. Check the renderer bundle before relying on an optional operation. - Do not claim a render or audit passed unless its output was actually checked. - Keep citation text human-readable; do not place internal tool tokens in the document. ## Bundled resources The package includes the canonical renderer, OOXML notes, task playbooks, design references, examples, and reusable scripts. `references/manifest.txt` lists the bundled paths. Scripts are intended to be run from a writable working directory, while this skill directory remains the source of reusable helpers.