Document Skills DOCX

DOCX workbench

A .docx file is a ZIP archive of XML parts around one word/document.xml. Treat the format with respect: silent corruption is the default failure mode when agents edit the XML blind.

Step 0 — Resolve paths and check the toolchain

Resolve this Skill's directory once (SKILL_DIR = the folder containing this SKILL.md), then check what is installed before promising anything:

python -c "import docx; print(docx.__version__ if hasattr(docx,'__version__') else 'ok')"

• python-docx present -> full create/read/edit support.
• python-docx missing but pandoc present -> read/extract requests can still be served by the pandoc route in references/read.md; report that structural reads, edits, and creation are unavailable (pip install python-docx) and stop only for those routes. Never hand-write OOXML as a substitute.
• Both missing -> report the missing tools and stop.
• pandoc present -> prefer it for text/markdown extraction (fast, faithful).
• soffice present -> enables the PDF smoke test in postcheck.

Step 1 — Classify the task

Two depth references slot in before create/edit: references/cjk.md whenever the document contains CJK text (east-asian fonts, 字号, char-based indents, 公文 geometry), and references/scenes.md when the request matches a known scene - academic paper, resume, official document (公文), or contract.

Two routes can chain (read -> edit, create -> review). Never skip classification; it decides between python-docx generation and raw XML surgery, which have opposite safety profiles.

Step 2 — Shared rules that always apply

1. Never edit word/document.xml with find/replace on rendered text. Run-level splits mean the visible word "contract" may be spread across three <w:t> nodes. Use the edit route's paragraph-index addressing instead.
2. Prefer modifying an existing document with python-docx when the change is structural (add paragraphs, tables, images, styles); drop to raw XML only for things python-docx cannot express (field codes, exotic properties, tracked-change surgery).
3. Always write to a new output path first. Only overwrite the source when the user explicitly asked for in-place modification, and then only after the postcheck passes.
4. Keep styles semantic. Use Heading 1..4 styles instead of "bold 16pt text" so navigation, TOC fields, and accessibility keep working.
5. Units: lengths in the XML are twentieths of a point (twips); python-docx accepts .inches/.cm/.Pt helpers - use the helpers.
6. Non-ASCII: write files as UTF-8 without BOM; declare encoding when opening text side files.

Step 3 — Execute the route

Follow the referenced file for concrete code patterns, then continue to postcheck. Do not improvise container-level operations (re-zipping, renaming parts) outside the patterns in references/edit.md.

Step 4 — Postcheck (mandatory before handing back the file)

Run every applicable item and report results explicitly:

1. Re-open the output with python-docx (Document(path)); confirm it parses and count paragraphs/tables.
2. If soffice exists: soffice --headless --convert-to pdf <output.docx> --outdir <tmp> must exit 0; the PDF is a smoke test, keep or delete it per the user's ask.
3. Verify requested features landed: search the re-opened document for the expected heading texts, table row counts, or inserted image count.
4. Report: output path, paragraph/table counts, what was verified, what could not be verified locally (e.g. exact pagination in MS Word), and any font substitutions expected.

If a check fails, fix and re-run; do not deliver with a known-broken archive.