--- name: docx description: Read, create, edit, and review Microsoft docx files; handle tracked changes, comments, and OOXML workflows. Includes scripts for common docx automation like extracting content, applying edits, and managing reviews at scale. Use for Word/docx editing or tracked changes. --- # DOCX Editing and Review ## Overview Use `python-docx` for simple operations. For tracked changes, comments, or OOXML manipulation, see the Advanced Workflows section below. Use absolute paths for all script invocations (e.g. `/root/workspace/Report.docx`). ## Add Comments Use `/root/skills/docx/scripts/add_comments.py` to add review comments from a JSON file: ```bash python /root/skills/docx/scripts/add_comments.py /root/workspace/file.docx /root/tmp/comments.json --author "Reviewer" ``` comments.json format: ```json [ { "id": "CMT-001", "page": 1, "section": "Section 2.1", "text": "Please clarify the encryption standards used.", "severity": "Major", "status": "Open", "quote": "encryption at rest" } ] ``` Fields: `id` (optional), `page`, `section`, `text`, `severity` (Critical/Major/Minor/Info), `status` (Open/Pending/Accepted/Rejected/Closed), `quote` (optional, for precise placement) --- ## Programmatic Text Extraction When you need structured text outside of the view tool: ```python from docx import Document doc = Document('/root/workspace/file.docx') for para in doc.paragraphs: print(para.text) ``` To see tracked changes inline, convert to markdown with pandoc: ```bash pandoc --track-changes=all /root/workspace/file.docx -o /root/tmp/output.md ``` ## Creating DOCXs ```python from docx import Document from docx.shared import Pt doc = Document() doc.add_heading('Document Title', 0) para = doc.add_paragraph() run = para.add_run('Bold text') run.bold = True table = doc.add_table(rows=2, cols=2) table.cell(0, 0).text = 'Header 1' doc.save('/root/workspace/output.docx') ``` For pixel-precise layouts or rich styling that `python-docx` can't express, use `docx@latest` (Node.js, pre-installed). See `docx-js.md` for full examples: ```javascript const { Document, Packer, Paragraph, TextRun } = require("docx"); const fs = require("fs"); const doc = new Document({ sections: [ { children: [ new Paragraph({ children: [new TextRun({ text: "Hello", bold: true })], }), ], }, ], }); Packer.toBuffer(doc).then((buffer) => fs.writeFileSync("/root/workspace/output.docx", buffer) ); ``` ## Editing DOCXs ```python from docx import Document doc = Document('/root/workspace/file.docx') for para in doc.paragraphs: if 'old text' in para.text: for run in para.runs: run.text = run.text.replace('old text', 'new text') doc.save('/root/workspace/file.docx') ``` --- ## Advanced Workflows (OOXML) Use these for tracked changes, comments, and direct XML manipulation. Simple edits (no comments or tracked changes) should use `python-docx` directly on the `.docx` file. ### Unpack/Pack The `Document` class for tracked changes and comments requires an unpacked directory. Always unpack first: ```bash # Unpack the DOCX to a working directory python /root/skills/docx/ooxml/scripts/unpack.py /root/workspace/file.docx /root/tmp/file_unpacked/ # ... edit using Document API (see below) ... # Pack back to DOCX (overwrites original) python /root/skills/docx/ooxml/scripts/pack.py /root/tmp/file_unpacked/ /root/workspace/file.docx ``` ### Complete Example: Adding Comments via OOXML ```bash # 1. Unpack python /root/skills/docx/ooxml/scripts/unpack.py /root/workspace/Protocol.docx /root/tmp/Protocol_unpacked/ # 2. Edit with Python python - << 'EOF' import sys sys.path.insert(0, '/root/skills/docx') from scripts.document import Document doc = Document('/root/tmp/Protocol_unpacked', author='Reviewer', initials='RV') main = doc['word/document.xml'] para = main.find_paragraph_containing('3. Study Design') if para: doc.add_comment(start=para, end=para, text='Clarify dosing schedule with clinical team.') doc.save() EOF # 3. Pack back python /root/skills/docx/ooxml/scripts/pack.py /root/tmp/Protocol_unpacked/ /root/workspace/Protocol.docx # 4. Verify python /root/skills/docx/scripts/list_changes.py /root/workspace/Protocol.docx ``` ### Tracked Changes: Supported API There is no `suggest_insertion_after`. Use the existing helpers: - `suggest_deletion(elem)` marks old text/paragraph as deleted - `DocxXMLEditor.suggest_paragraph(xml)` wraps a new paragraph in `` - `insert_after(elem, xml_string)` places the insertion in the same parent/cell Minimal replace-with-redline pattern: ```python import sys sys.path.insert(0, '/root/skills/docx') import html from scripts.document import Document, DocxXMLEditor as DX doc = Document('/root/tmp/unpacked_dir', author='Reg Team', initials='RT') main = doc['word/document.xml'] def make_para(text: str) -> str: raw = ('' f'{html.escape(text)}') return DX.suggest_paragraph(raw) def redline_para(old_text, new_text): p = main.get_node(tag='w:p', contains=old_text) main.suggest_deletion(p) main.insert_after(p, make_para(new_text)) ``` ### Document Library ```python import sys sys.path.insert(0, '/root/skills/docx') from scripts.document import Document doc = Document('/root/tmp/file_unpacked', author="DocAgent", track_revisions=True) main = doc["word/document.xml"] para = main.find_paragraph_containing("paragraph text") if para: doc.add_comment(start=para, end=para, text="Comment on this paragraph") doc.save() ``` See `ooxml.md` for detailed OOXML patterns. ### Troubleshooting: Text Not Found If `get_node(contains="...")` fails because text is split across runs, use `find_paragraph_containing` which handles run-spanning and Unicode normalization: ```python main = doc["word/document.xml"] para = main.find_paragraph_containing("batch formulas are provided") if para: doc.add_comment(start=para, end=para, text="Your comment") # List paragraphs to find correct search text for i, text, elem in main.list_paragraphs(limit=20): print(f"[{i}] {text}") ``` ## Review Workflow (Accept/Reject Changes) List all tracked changes: ```bash python /root/skills/docx/scripts/list_changes.py /root/workspace/file.docx ``` Accept all changes (clean document, edits in place): ```bash python /root/skills/docx/scripts/accept_all.py /root/workspace/file.docx ``` Reject all changes (restore original, edits in place): ```bash python /root/skills/docx/scripts/reject_all.py /root/workspace/file.docx ``` Verify clean state: ```bash pandoc --track-changes=all /root/workspace/file.docx -o /root/tmp/verify.md ``` Fine-grained accept/reject (saves to a separate output file): ```bash python /root/skills/docx/scripts/review.py /root/workspace/file.docx /root/workspace/output.docx # Commands: list | accept | reject | accept-all | reject-all # resolve | delete | save | quit ``` --- ## Visual Verification (REQUIRED) After meaningful layout or styling changes, use the view tool with `mode="visual"` on the document path to confirm formatting. If view rendering is insufficient for a specific check, use the render script as a fallback: ```bash python /root/skills/docx/scripts/render_docx.py /root/workspace/file.docx --output_dir /root/tmp/docx_render ``` Then inspect the images with the view tool. Inspect every affected page. If anything looks off (clipped text, misaligned tables, broken bullets), fix the DOCX and re-render until clean. ## Quality Expectations - **Client-ready output**: Deliver consistent typography, spacing, margins, and clear heading hierarchy - **No formatting defects**: No clipped/overlapping text, broken tables, unreadable characters, or default-template styling - **No AI citation tokens**: Never include `[145036110387964†L158-L160]` or `【turn...】`; citations must be human-readable - **Unicode hygiene**: Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes unless present in original - **Charts and tables**: Must be legible in rendered pages with correct alignment - **Preserve existing styles**: When editing, match existing formatting exactly ## Final Checks (REQUIRED BEFORE DELIVERY) **Do not deliver until the latest rendered inspection shows zero visual or formatting defects.** 1. **Render and inspect at 100% zoom**: Re-render every affected page after any meaningful change 2. **Zero visual defects**: No clipped/overlapping text, broken tables, unreadable characters, or default-template styling 3. **Fix and re-render loop**: If any spacing, alignment, or pagination issues found, fix and repeat 4. **Typography verification**: Consistent fonts, spacing, margins, and clear heading hierarchy 5. **Tables and diagrams**: Must be legible with correct alignment in rendered pages 6. **Clean up**: Remove temp files and duplicate renders after final approval **Quality Gate Checklist:** - [ ] All pages rendered and inspected at full resolution - [ ] No AI citation tokens or placeholder strings - [ ] ASCII hyphens only (no U+2011 non-breaking hyphens or other Unicode dashes) - [ ] Tables render correctly without broken cells or overflow - [ ] Tracked changes (if any) display correctly - [ ] Comments placed on correct paragraphs **Pre-installed in sandbox:** - `python-docx` - Word document manipulation - `docx` (Node.js) - Advanced DOCX generation - `pandoc` - Markdown/tracked-changes conversion - `LibreOffice` - PDF conversion for visual verification

pdf

Scan your own AI components