DOCX Creation, Editing, and Analysis

The Problem It Solves

When building automated document pipelines, you often need to manipulate Word documents programmatically. Whether generating uniform reports from data, batch-updating contract templates, or extracting specific content from agreements, working directly with .docx files presents a core challenge: how to reliably read and write their complex internal structure.

How the Skill Works

This skillset is built on a fundamental understanding: a .docx file is a ZIP archive containing XML files. Its operations are organized around this structure into two primary directions:

1. Creating New Documents
The docx JavaScript library (npm install -g docx) is used to generate new documents from scratch. Key steps and rules include:
* Page Setup: Page dimensions must be explicitly set using DXA units (1 inch = 1440 DXA). For US documents, use US Letter (12240 x 15840) instead of the default A4.
* Structural Elements: When creating paragraphs, lists, and tables, strict best practices must be followed. For example, lists must use LevelFormat.BULLET with numbering configuration; never use unicode bullet symbols. Tables have a critical requirement: you must set both columnWidths for the entire table and a width for each individual cell, and these must match. Always use WidthType.DXA — percentage mode breaks in platforms like Google Docs.
* Style Overrides: Default heading styles can be overridden using exact built-in IDs (e.g., "Heading1"), and outlineLevel must be included for Table of Contents generation.
* Validation: After creation, the file should be validated immediately. If validation fails, unpack it to fix the XML.

2. Editing Existing Documents
A strict three-step workflow is followed:
1. Unpack: Extract the .docx to formatted XML, performing tasks like converting smart quotes to XML entities (“, etc.) and merging adjacent runs.
2. Edit XML: Directly edit the files in unpacked/word/. This is the core of modification. Key operational guidelines:
* Modification Method: Use the Edit tool for direct string replacement. Do not write Python scripts, as they introduce unnecessary complexity and make the replacement less explicit.
* Tracked Changes & Comments: When adding tracked changes or comments, any new text containing apostrophes or quotes must use XML entities (e.g., ’ for right single quote) to produce smart quotes. Adding comments requires inserting markers across multiple XML files.
* Image Addition: Involves placing the image in word/media/, adding corresponding entries to the relationship file (document.xml.rels) and content types file ([Content_Types].xml), and finally referencing it in the document XML.
3. Pack: Repack into a DOCX. The tool performs auto-repair (e.g., fixing out-of-range durableId, adding xml:space="preserve") but cannot fix malformed XML or schema violations.

Use Cases and Critical Constraints

This skillset is ideal for scenarios requiring batch processing, programmatic generation, or precise editing of Word documents. It leverages pandoc for text extraction, the docx library for creation, and the unpack-edit-repack workflow for modifications. Processing legacy .doc files or PDF conversion relies on LibreOffice (soffice.py handles CJK locale settings).

Critical points to note:
* Editing existing documents is fundamentally a string replacement operation on text content. For extremely complex formatting or macros, the unpacked XML can become difficult to maintain.
* When an editing tool (like an AI assistant) adds tracked changes, it should default to using “Claude” as the author name unless explicitly instructed otherwise.
* The auto-repair function is limited. XML validation before repacking is crucial.
* For Chinese content, especially legacy .doc files encoded in GBK, ensure the conversion environment (LibreOffice) supports the zh_CN.UTF-8 locale.