docx

DOCX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Prerequisites

Python dependencies are resolved automatically by uv run — scripts declare them in PEP 723 headers. The workflows below also rely on:

• pandoc (brew install pandoc) — text extraction to markdown
• LibreOffice (brew install --cask libreoffice) and poppler (brew install poppler) — converting documents to images (soffice, pdftoppm)
• Node.js packages — creating new documents uses the docx npm package; if node_modules/ is missing, run npm install in this skill directory once

Workflow Decision Tree

Reading/Analyzing Content

Use "Text extraction" or "Raw XML access" sections below

Creating New Document

Use "Creating a new Word document" workflow

Editing Existing Document

• Your own document + simple changes Use "Basic OOXML editing" workflow

• Someone else's document Use "Redlining workflow" (recommended default)

• Legal, academic, business, or government docs Use "Redlining workflow" (required)

Reading and analyzing content

Text extraction

If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

Raw XML access

You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.

Unpacking a file

uv run ooxml/scripts/unpack.py <office_file> <output_directory>