DOC: Professional DOCX Document Creation with Visual Validation

The DOC skill from OpenAI enables AI assistants to read, create, and edit DOCX documents with emphasis on formatting fidelity and visual validation. Rather than treating documents as plain text with styling afterthoughts, this skill prioritizes layout, tables, diagrams, and pagination—using visual review to ensure professional formatting before delivery.

What This Skill Does

This skill provides comprehensive DOCX document handling with three core capabilities: reading DOCX content while preserving layout understanding, creating professionally formatted documents using python-docx with proper styling, and validating visual output through DOCX-to-PDF-to-PNG rendering pipelines that reveal how documents actually appear rather than how code describes them.

The workflow emphasizes visual review throughout the editing process. After each meaningful change, the skill re-renders documents and inspects actual pages, catching formatting defects like clipped text, broken tables, incorrect alignment, or pagination issues before final delivery. This prevents the common pitfall of generating structurally correct but visually broken documents.

Two rendering paths support visual validation. When LibreOffice (soffice) and Poppler (pdftoppm) are available, the skill converts DOCX to PDF then PDF to PNGs for inspection. Alternatively, the bundled scripts/render_docx.py helper (requiring pdf2image and Poppler) handles the full pipeline. If rendering tools are unavailable, the skill extracts text with python-docx while explicitly calling out layout validation risk.

Getting Started

The skill prefers uv for Python dependency management, installing python-docx and pdf2image packages. When uv isn't available, it falls back to standard pip installation. System tools LibreOffice and Poppler enable rendering—macOS users install via Homebrew (brew install libreoffice poppler), Ubuntu/Debian users via apt (sudo apt-get install libreoffice poppler-utils).

Workspace organization keeps intermediate files separate from deliverables. The tmp/docs/ directory holds intermediate renders and conversions (these are deleted when work completes), while output/doc/ contains final artifacts. This separation prevents cluttering workspaces with rendering artifacts while maintaining organized final outputs.

The python-docx library provides structured creation and editing capabilities. It handles headings with style hierarchies, tables with cell formatting, lists (bulleted and numbered), inline styling (bold, italic, fonts), and paragraph spacing/alignment. This enables professional document creation without manual XML manipulation.

Key Features

Visual Validation Pipeline: The skill converts DOCX to PDF using LibreOffice's headless mode, then PDF to PNG sequences using Poppler's pdftoppm. This reveals exact visual appearance including layout, font rendering, table structure, and pagination—catching issues invisible in code or text extraction.

Structured Document Creation: Using python-docx, the skill applies proper style hierarchies, creates tables with correct formatting, implements numbered and bulleted lists, manages inline text styling, and controls spacing and margins. Documents follow professional formatting conventions rather than ad-hoc styling.

Iterative Refinement Loop: After each significant change, the skill re-renders and inspects pages at 100% zoom. Formatting issues trigger fixes and repeated renders until pages are client-ready. This tight feedback loop ensures quality before final delivery.

Layout Fidelity Awareness: The skill understands that layout matters. When visual review isn't possible (missing rendering tools), it explicitly communicates layout validation risk rather than silently delivering potentially broken documents.

Quality Standards Enforcement: Generated documents must be client-ready with consistent typography, proper spacing and margins, clear hierarchy, no clipped or overlapping text, legible charts and tables with correct alignment, and ASCII hyphens only (avoiding Unicode dash characters that cause issues).

Usage Examples

When creating a technical report with tables and diagrams, the skill uses python-docx to structure content with heading hierarchies, inserts data tables with formatted headers, adds charts or diagrams as image objects, applies consistent paragraph spacing, then renders to PNG and inspects every page verifying tables don't break across pages inappropriately and diagrams remain legible.

For editing existing documents, the skill reads the DOCX to understand current structure, makes targeted modifications using python-docx (updating specific paragraphs, reformatting tables, adjusting styles), renders the modified document, inspects changes to confirm no unintended layout shifts occurred, and iterates until modifications integrate cleanly without breaking existing formatting.

When producing client deliverables requiring specific branding or formatting standards, the skill creates custom styles matching brand guidelines, applies consistent fonts and colors, ensures proper margins and spacing throughout, validates page breaks occur at logical points, then delivers final DOCX after visual confirmation that every page meets professional standards.

Best Practices

Always render and inspect visually before final delivery. Code that generates syntactically correct DOCX can still produce visually broken documents. Only visual inspection at 100% zoom reveals actual appearance including subtle issues like incorrect line heights, misaligned elements, or pagination problems.

Use styles rather than direct formatting whenever possible. Python-docx supports style-based formatting which maintains consistency better than applying formatting directly to each element. Define heading styles, paragraph styles, and table styles then apply them consistently throughout documents.

Avoid Unicode dashes and special characters unless necessary. The skill enforces ASCII hyphens because Unicode variants (non-breaking hyphens, em dashes) cause compatibility issues across different systems and software versions. When special characters are required, verify they render correctly in the visual validation step.

Keep intermediate files organized and clean them up. Use tmp/docs/ for rendering artifacts created during development, delete these when work completes, and only maintain final deliverables in output/doc/. This prevents workspace clutter and confusion about which files are current.

Fix issues immediately when visual inspection reveals them. Don't accumulate formatting defects planning to "fix them later." The iterative render-inspect-fix loop works best when issues are addressed as soon as discovered, before subsequent changes compound problems.

When to Use This Skill

Use this skill when creating or editing DOCX documents where formatting and layout fidelity matter. Reports, proposals, technical documentation, client deliverables—anything representing professional communication benefits from visual validation ensuring polished presentation.

The skill is particularly valuable for complex documents with tables, charts, diagrams, or intricate layouts. These elements are prone to rendering issues that text extraction doesn't reveal. Visual validation catches these problems before documents reach recipients.

It's ideal when working with templates or brand requirements. The combination of python-docx's structured creation and visual validation ensures documents not only use correct styles in code but actually appear correctly when opened in Word or other DOCX-compatible software.

When NOT to Use This Skill

Don't use this skill for simple text documents where formatting doesn't matter. Quick notes, draft content, or informal communications don't justify the rendering and visual validation overhead. Plain text handling or simpler document skills suffice.

Avoid using it when visual rendering tools can't be installed in the environment. While the skill can extract text as fallback, its value proposition is visual validation. Without rendering capability, simpler text-focused approaches are more appropriate.

It's not appropriate for other document formats. This skill is specific to DOCX (Microsoft Word format). For PDFs, use PDF-specific skills. For Markdown, plain text, or other formats, use format-appropriate tools.

Don't expect the skill to make content or design decisions. It ensures documents are formatted correctly and visually polished, but doesn't determine whether content is well-written, information is well-organized, or design choices are optimal.

Related Skills

This skill complements docx (Anthropic's DOCX skill), pdf for PDF document handling, and pptx for PowerPoint creation with similar visual validation principles.

Source

This skill is maintained by OpenAI. View on GitHub