DOCX: Professional Word Document Creation and Editing
The DOCX skill from Anthropic enables AI assistants to create, read, edit, and manipulate Word documents with professional formatting. Unlike simple text manipulation, this skill handles the complexities of DOCX files as ZIP archives containing XML, managing document structure, formatting, tables, images, tracked changes, and comments while maintaining compatibility across platforms.
What This Skill Does
This skill provides comprehensive DOCX handling through three approaches: creating new documents with docx-js (JavaScript library for structured document generation), editing existing documents via XML manipulation (unpack-edit-repack workflow), and reading content through pandoc or raw XML access for analysis.
For creating new documents, the skill uses docx-js to generate properly structured Word files with professional elements—tables of contents, formatted headings, page numbers, headers and footers, tables with precise sizing, embedded images, bulleted and numbered lists, and multiple sections with different page orientations. Output files are validated to ensure compatibility across Word, Google Docs, and LibreOffice.
Editing existing documents follows an unpack-edit-repack pipeline: extract XML files from the DOCX archive with pretty-printing and run merging for easier editing, modify XML directly using the Edit tool (no Python scripts needed), add tracked changes or comments using dedicated scripts, then repack into valid DOCX with auto-repair of common XML issues. This workflow enables surgical edits without opening Word.
Getting Started
The skill requires several dependencies: pandoc for text extraction, docx-js (npm install -g docx) for creating new documents, LibreOffice for PDF conversion (auto-configured via scripts/office/soffice.py), and Poppler's pdftoppm for converting PDFs to images.
For reading DOCX content, pandoc extracts text while preserving tracked changes: pandoc --track-changes=all document.docx -o output.md. Raw XML access via unpacking provides complete control: python scripts/office/unpack.py document.docx unpacked/ extracts all files with XML pretty-printing and smart quote conversion.
Creating new documents begins with JavaScript code using docx-js. After generating files, validation catches common errors: python scripts/office/validate.py doc.docx. If validation fails, the skill unpacks, fixes XML issues, and repacks. This ensures files work reliably across platforms.
Key Features
Professional Document Creation: Using docx-js, the skill generates documents with precise page sizing (defaulting to US Letter, not A4), proper style hierarchies for headings, tables with dual width specifications (table-level and cell-level for cross-platform compatibility), embedded images with required metadata, page breaks and section breaks, and headers/footers with page numbers.
XML-Based Editing: The unpack-edit-repack workflow enables sophisticated edits without Word. Scripts handle XML pretty-printing, adjacent run merging for simpler editing, smart quote entity conversion, tracked change insertion/deletion/restoration, comment addition with threading, and auto-repair of common XML issues during packing.
Tracked Changes Support: The skill adds tracked changes XML marking insertions with author/date, deletions with instead of , minimal edits (only marking what changed), paragraph mark deletion for removing entire paragraphs, nested deletions to reject others' insertions, and insertion after deletions to restore removed content.
Comment Management: A dedicated script (comment.py) handles boilerplate across multiple XML files. It generates comment IDs, creates comment XML with proper escaping, enables comment threading for replies, allows custom author names, then users add range markers to document.xml to position comments.
Image and Asset Handling: The skill converts DOCX to PDF then PDF to images for visual preview, embeds images in documents with proper relationships and content types, requires explicit image type specification (png/jpg/etc), and provides alt-text support for accessibility.
Usage Examples
When creating a professional report with branding, the skill generates documents with custom page sizes matching company letterhead, headers containing logos (positioned and sized correctly), formatted tables showing data with proper borders and shading, embedded charts as images, style-based formatting for consistency, and tables of contents with automatic hyperlinks.
For editing contracts with tracked changes, the skill unpacks the existing DOCX, uses the Edit tool to replace terms (marking deletions and insertions with proper XML), preserves original formatting by copying blocks into tracked change runs, marks paragraph deletions so accepting changes merges paragraphs correctly, repacks with validation, and converts to PDF for visual verification.
When collaborating on documents with comments, the skill unpacks the DOCX, runs comment.py to generate comment XML with escaped text, adds comment range markers in document.xml around relevant text, nests reply comments inside parent comments for threading, repacks the document, and verifies comments appear correctly in Word.
Best Practices
Always set page size explicitly when creating documents. Docx-js defaults to A4; specify US Letter (12240 x 15840 DXA) for US audiences to prevent unexpected layout shifts when opening files in Word.
Use style-based formatting rather than direct formatting whenever possible. Define custom paragraph styles overriding built-in heading styles ("Heading1", "Heading2") with exact IDs, then apply consistently throughout documents. This maintains formatting consistency and enables bulk style updates.
Never use Unicode bullet characters in list items. Instead, use proper numbering configuration with LevelFormat.BULLET. Manually inserting bullet characters breaks list functionality and creates formatting issues across platforms.
For tables, always specify both table-level width and individual cell widths using DXA units (not percentages, which break in Google Docs). Ensure column widths sum to table width, and include cell margins for proper padding without affecting width calculations.
Use the Edit tool directly for XML changes rather than writing Python scripts. The Edit tool shows exactly what's being replaced, making it easier to verify changes before applying them. Scripts add unnecessary complexity for simple string replacement.
When to Use This Skill
Use this skill when creating or editing professional Word documents where formatting, structure, and cross-platform compatibility matter. Reports, proposals, contracts, templates, letters—anything requiring polished presentation in Word format benefits from this skill's capabilities.
The skill is particularly valuable when automated document generation or batch editing is needed. Creating dozens of customized contracts, updating headers across multiple templates, or inserting tracked changes programmatically all leverage the unpack-edit-repack workflow efficiently.
It's ideal when working with tracked changes or comments programmatically. Legal document review, collaborative editing workflows, or automated suggestion insertion all require XML-level manipulation that this skill provides.
When NOT to Use This Skill
Don't use this skill for simple text documents where formatting doesn't matter. Plain text files or markdown are more appropriate than DOCX for unformatted content.
Avoid using it for final visual design requiring pixel-perfect control. While the skill creates professional documents, complex layouts with intricate positioning are better suited to design software than Word's document model.
It's not appropriate for other document formats. This skill handles DOCX specifically. For PDFs, spreadsheets, or presentations, use format-appropriate skills.
Don't expect the skill to make content decisions. It handles document structure, formatting, and XML manipulation, but doesn't determine whether content is well-written, arguments are sound, or designs are effective.
Related Skills
This skill complements doc (OpenAI's DOCX skill), pdf for PDF document handling, pptx for PowerPoint presentations, and xlsx for Excel spreadsheets.
Source
This skill is maintained by Anthropic. View on GitHub