docx

1---2name: docx3description: Create, read, edit, template, and review Word .docx files.4version: 1.1.05author: Nous Research6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [word, docx, documents, office, templates, revisions, comments]11    category: productivity12    related_skills: [pdf, xlsx, powerpoint]13---14 15# Docx Skill16 17Create, read, edit, and template Microsoft Word `.docx` files with18python-docx via small CLIs. It handles text, styles, lists, tables,19images, headers/footers, `{{token}}` templating, tracked changes20(list/accept/reject), comments (list/add/delete), TOC and page-number21fields, and package health checks. It does not render documents itself22(PDF needs LibreOffice — see Converting to PDF) or edit legacy `.doc`.23 24## When to Use25 26- The user asks to generate a Word document (report, letter, contract).27- You need the text, outline, styles, or embedded images of a `.docx`.28- You must change an existing `.docx`: replace text, edit table cells,29  insert/delete paragraphs, apply styles, merge fragmented runs.30- You have a `.docx` template with `{{placeholders}}` to fill from data.31- The document has tracked changes to review, accept, or reject.32- You need to read reviewers' comments, or add/delete comments.33- A `.docx` won't open or behaves oddly and you need corruption triage.34- The document needs a table of contents or "Page X of Y" footers.35- Not for: `.doc` (legacy), `.odt`, or WYSIWYG layout work.36 37## Prerequisites38 39- Python 3.10+ with `python-docx` installed:40  `pip install python-docx` (import name is `docx`; lxml comes with it).41- Comments `add` uses the native API on python-docx >= 1.2 and an XML42  fallback on older versions — both are automatic.43- For image blocks: the image files must exist locally (PNG/JPEG).44 45## How to Run46 47All helpers live in `scripts/` next to this file. Run them with the48`terminal` tool; each supports `--help` and prints JSON to stdout.49 50```bash51python scripts/docx_create.py spec.json out.docx52python scripts/docx_read.py out.docx --text53python scripts/docx_edit.py replace out.docx --find old --replace new54python scripts/docx_template.py tpl.docx values.json filled.docx55python scripts/docx_revisions.py list out.docx56python scripts/docx_comments.py list out.docx57python scripts/docx_validate.py out.docx58```59 60## Quick Reference61 62| Task | Command |63| --- | --- |64| Create from JSON spec | `docx_create.py spec.json out.docx` |65| Full text (body+tables+headers/footers) | `docx_read.py f.docx --text` |66| Heading outline + table shapes | `docx_read.py f.docx --structure` |67| Styles actually used | `docx_read.py f.docx --styles` |68| Extract embedded images | `docx_read.py f.docx --images outdir/` |69| Detect tracked changes/comments | `docx_read.py f.docx --revisions` |70| Find/replace (formatting kept) | `docx_edit.py replace f.docx --find A --replace B -o out.docx` |71| Set a table cell | `docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X` |72| Insert paragraph before index N | `docx_edit.py insert f.docx --index N --text X --style Normal` |73| Delete paragraph N | `docx_edit.py delete f.docx --index N` |74| Apply style to paragraph N | `docx_edit.py style f.docx --index N --style "Heading 1"` |75| Merge equal-format adjacent runs | `docx_edit.py normalize f.docx -o out.docx` |76| Insert TOC field before para N | `docx_edit.py toc f.docx --index N -o out.docx` |77| "Page X of Y" footer fields | `docx_edit.py page-numbers f.docx` |78| Fill `{{tokens}}` | `docx_template.py tpl.docx values.json out.docx --strict` |79| List revisions (id/author/date/text) | `docx_revisions.py list f.docx` |80| Accept / reject all revisions | `docx_revisions.py accept-all f.docx -o out.docx` (or `reject-all`) |81| Accept / reject one revision | `docx_revisions.py accept f.docx --id 3 -o out.docx` |82| List comments (+anchored text) | `docx_comments.py list f.docx` |83| Add comment anchored to text | `docx_comments.py add f.docx --target "phrase" --text "note" --author You` |84| Delete comment by id | `docx_comments.py delete f.docx --id 0` |85| Health-check the package | `docx_validate.py f.docx` (exit 1 on errors) |86 87## Procedure88 891. **Create.** Write a JSON spec with `write_file`, then run90   `scripts/docx_create.py`. The spec supports: `page` (size + margins in91   mm), `header`/`footer` strings, `footer_page_numbers` (adds a92   "Page X of Y" field footer), `styles` (custom paragraph styles with93   font, size, bold/italic, hex `color`), and `blocks` — `heading`94   (level 1-9), `paragraph` (either `text` or a `runs` list where each run95   may set `bold`/`italic`/`underline`), `bullet_list`, `numbered_list`,96   `table` (`header` row rendered bold, `rows`, optional built-in table97   `style` such as `Table Grid`), `image` (`path`, optional `width_mm`),98   `toc` (Table of Contents field), and `page_break`. The full spec99   format is documented at the top of `scripts/docx_create.py`.1002. **Read.** Use `scripts/docx_read.py` with exactly one mode flag.101   `--text` returns body paragraphs, all table cell text, and102   header/footer text as JSON. `--structure` returns the heading outline103   plus paragraph/table/section counts. `--images DIR` copies every file104   under `word/media/` out of the package.1053. **Edit.** Use `scripts/docx_edit.py`. `replace` walks body, tables106   (nested included), headers and footers, and preserves run formatting;107   add `--body-only` to skip headers/footers. Pass `-o out.docx` to keep108   the original; omit it to edit in place. Paragraph indices for109   `insert`/`delete`/`style`/`toc` refer to `--structure`/`--text` body110   order. Run `normalize` first on documents that came out of heavy Word111   editing — it merges adjacent runs with identical formatting so later112   find-replace matches reliably.1134. **Review revisions.** `docx_revisions.py list` reports every `w:ins`114   and `w:del` (id, author, date, affected text) anywhere in body,115   tables, headers, or footers. `accept-all` / `reject-all` resolve them116   in bulk; `accept`/`reject --id N` handles a single revision. Accept117   keeps insertions and drops deleted text; reject does the reverse.1185. **Comments.** `docx_comments.py list` returns each comment's id,119   author, date, body text, and the document text it is anchored to.120   `add --target "some phrase"` anchors a new comment to the first121   occurrence of that phrase (runs are split as needed; formatting is122   preserved). `delete --id N` removes the comment and its markers123   without touching document text.1246. **Template.** Put `{{name}}`-style tokens in the document. Run125   `scripts/docx_template.py` with a JSON object of values. Use126   `--strict` to fail when tokens remain unfilled; the JSON output lists127   `filled` counts and `unfilled_tokens` either way.1287. **Verify** (always): re-read the output with `--text` or129   `--structure`, and run `docx_validate.py` on anything you produced130   via revision/comment surgery.131 132## Converting to PDF133 134No script needed. When LibreOffice is installed, convert headlessly:135 136```bash137soffice --headless --convert-to pdf --outdir outdir/ file.docx138```139 140Check availability first (`command -v soffice || command -v141libreoffice`). If neither exists, tell the user PDF conversion is142unavailable in this environment rather than improvising — python-docx143cannot render PDFs, and layout fidelity requires a real renderer.144 145## Pitfalls146 147- **Tokens split across runs.** Word often fragments text into several148  runs. The replace helpers collapse matched runs (replacement inherits149  the first run's formatting); running `docx_edit.py normalize` first150  reduces fragmentation for all later edits.151- **Revision coverage.** `docx_revisions.py` resolves run-level152  insertions and deletions (the overwhelming majority). Paragraph-mark153  and table-row revisions, format-change records, and moves are detected154  by `--revisions` but not auto-resolved — see155  `references/revisions-and-comments.md` and hand those to Word.156- **Comment threading.** Replies and "resolved" status live in157  `commentsExtended.xml`, which this skill ignores; comments it adds are158  plain top-level comments.159- **Field results are computed by Word.** `toc`, `page-numbers`, and the160  `toc`/`footer_page_numbers` spec options write *field codes*.161  Word/LibreOffice populates the actual entries and numbers when the162  file is opened (Word may prompt to update fields); python-docx never163  computes them, so placeholder text shows until then.164- **Validation is a health check, not schema validation.**165  `docx_validate.py` verifies the zip, required parts, relationship166  targets, image magic bytes, and referenced styles. It is NOT XSD167  validation — a file can pass and still contain XML Word dislikes.168- **Style names must exist.** Applying a style that isn't defined in the169  document raises `KeyError`. Built-ins like `Heading 1`, `List Bullet`,170  `List Number`, `Table Grid` exist in the default template; custom171  styles must be declared in the create spec first.172- **Numbered lists restart.** `List Number` relies on Word's default173  numbering; separate lists in one document may continue numbering174  instead of restarting. Warn users needing precise multi-list numbering.175- **Cell writes replace formatting.** `set-cell` uses `cell.text = ...`,176  which resets runs in that cell to plain formatting.177- **Encoding.** All JSON specs/values files are read as UTF-8 explicitly;178  never rely on locale defaults when writing your own glue code.179- **Don't unzip-and-sed the XML.** Edit through the scripts (or180  python-docx); raw text substitution in `document.xml` corrupts files181  easily. Use `patch`/`write_file` only for the JSON inputs, never on the182  `.docx` itself.183 184## Verification185 186- After create/edit/template, run `docx_read.py out.docx --text` and187  check the expected strings appear (and old strings are gone).188- After accept/reject, `docx_revisions.py list` should return `[]` (or189  only the ids you intentionally left); after comment surgery,190  `docx_comments.py list` should reflect the change and `--text` output191  must be unchanged.192- `docx_validate.py out.docx` exits 0 with `"ok": true` on a healthy193  package — run it after any revision/comment/field manipulation.194- For templates run with `--strict`, or check `unfilled_tokens == []`.195- Structure checks: `--structure` should show the expected heading196  outline and table shapes; `--styles` confirms custom styles applied.197