---
name: docx
description: Use for all Word .docx tasks—create new documents, edit content, format text, read/extract text, unpack/repack OOXML, manage comments, and accept track changes. Invoke when the user mentions .docx, Word documents, memos, reports, or any deliverable as a Word file.
user-invocable: true
---

# WordprocessingML (DOCX) skill

A `.docx` is a ZIP of XML parts. This skill provides Python-native creation via **python-docx** (preferred), Node.js creation via **docx** npm package, and CLI tools under `scripts/` and `scripts/ooxml_kit/`.

## Must-read guide (load with `read_file`)

| File | When |
|------|------|
| [`word_ml_playbook.md`](word_ml_playbook.md) | **Creating** new documents (python-docx preferred, docx npm alternative), **reading** text, and **editing** unpacked OOXML—page geometry, styles, lists, tables, images, validation. |

## Decision tree

```
Need to CREATE a new .docx?           → word_ml_playbook.md (python-docx section)
Need to READ / EXTRACT text?          → word_ml_playbook.md (Reading section)
Need to EDIT an existing .docx?       → expand_ooxml_zip.py → edit XML → build_ooxml_zip.py
Need to SEARCH / REPLACE text?        → word_ml_playbook.md (Search and replace section)
Need HEADERS / FOOTERS / PAGE #s?     → word_ml_playbook.md (Headers / Page numbers sections)
Need a TABLE OF CONTENTS?             → word_ml_playbook.md (Table of Contents section)
Need CUSTOM STYLES?                   → word_ml_playbook.md (Custom styles section)
Need HYPERLINKS?                      → word_ml_playbook.md (Hyperlinks section)
Need to MERGE multiple .docx files?   → word_ml_playbook.md (Merging documents section)
Need to CONVERT formats (PDF/HTML)?   → word_ml_playbook.md (Format conversion section)
Need TEMPLATE / MAIL MERGE?           → word_ml_playbook.md (Mail merge / templating section)
Need to ACCEPT track changes?         → apply_tracked_resolutions.py
Need to ADD / EDIT comments?          → word_comment_tool.py
```

## OOXML kit (`scripts/ooxml_kit/`)

Run these with `cwd` resolved to the skill directory (as the Skill tool does).

| Script | Role |
|--------|------|
| `expand_ooxml_zip.py` | Unzip and pretty-print XML; optional run merge for adjacent runs and coalesce tracked spans (DOCX). |
| `build_ooxml_zip.py` | Repack folder to `.docx` / `.pptx` / `.xlsx` with optional validation vs an `--original` file. |
| `libreoffice_runner.py` | Headless LibreOffice with socket shim when needed (Linux). |
| `audit_ooxml_package.py` | Validate unpacked or packed Office XML (see `--original`, `--auto-repair`, `--author`). |

## DOCX-specific helpers

| Script | Role |
|--------|------|
| `apply_tracked_resolutions.py` | Accept all tracked changes via LibreOffice macro. |
| `word_comment_tool.py` | Maintain `comments.xml` and related parts; see inline usage. |

## Typical flows

- **Create new document**: use `python-docx` — see `word_ml_playbook.md` (preferred Python path).
- **Read text**: `python-docx` (see playbook) or `pandoc --track-changes=all file.docx -o out.md`.
- **Unpack**: `python scripts/ooxml_kit/expand_ooxml_zip.py doc.docx unpacked/`
- **Pack**: `python scripts/ooxml_kit/build_ooxml_zip.py unpacked/ out.docx --original doc.docx`
- **Convert legacy .doc**: `python scripts/ooxml_kit/libreoffice_runner.py --headless --convert-to docx file.doc`

Templates for comments live in `scripts/templates/` when using `word_comment_tool.py`.

## Dependencies

`python-docx` (creation/reading), `defusedxml`, `lxml`, LibreOffice optional for conversion and track-changes acceptance. Optional: `docxcompose` (merging), `docxtpl` (templating).

## Important: do not read .docx files with Read tool

After creating a `.docx` file, do **not** use the Read tool or Bash `view` to verify it — `.docx` files are binary ZIP archives and cannot be read as text. Instead:
- Confirm success from the python-docx script's stdout (e.g., `print("Created:", path)`)
- If verification is needed, write a short python-docx script to open the file and print paragraph text
- Always wrap the script body in `try/except` and print `ERROR:<type>:<message>` on failure
- **Only reference the file for delivery if the Bash output contains `SAVED:<path>`** — if the output shows an error or a non-zero exit code, the file was not created
