Word Document Editor

Word Document Editor Skill

Edit Word (.docx) documents without breaking any formatting. All text operations happen at the run level, preserving fonts, bold, italic, colors, sizes, and all other styling.

Core Principle

NEVER use paragraph.text = ... or cell.text = ... — these destroy run-level formatting. Always use the provided docx_utils.py script which operates at the XML run level.

Available Commands

The Python script is located at: {PLUGIN_DIR}/skills/docx-editor/scripts/docx_utils.py

Run all commands via Bash tool with python3:

1. View document info

python3 {SCRIPT} info "path/to/file.docx"

2. View table structure (see cell coordinates and merged cells)

python3 {SCRIPT} structure "path/to/file.docx" [table_index]

3. Replace text (format-preserving, cross-run safe)

python3 {SCRIPT} replace "input.docx" "output.docx" "old text" "new text"

4. Batch replace multiple fields

python3 {SCRIPT} batch_replace "input.docx" "output.docx" '{"${name}": "Alice", "${date}": "2026-01-01"}'

5. Fill a single table cell

python3 {SCRIPT} fill_cell "input.docx" "output.docx" <table_index> <row> <col> "text"

6. Batch fill table cells

python3 {SCRIPT} batch_fill "input.docx" "output.docx" '[{"row":0,"col":1,"text":"value1"},{"row":1,"col":2,"text":"value2"}]'

7. Read a table cell

python3 {SCRIPT} read_cell "file.docx" <table_index> <row> <col>

Workflow

When the user wants to edit a Word document:

1. Inspect first: Use info to see document structure, then structure to map table cell coordinates
2. Plan the edits: Identify which cells/text to modify based on the structure output
3. Execute edits: Use replace, batch_replace, fill_cell, or batch_fill as appropriate
4. Always save to a new file to preserve the original as backup

Prerequisites

• Python 3 with python-docx installed: pip install python-docx

Important Notes

• The script handles cross-run text matching — even if Word splits "{{name}}" across multiple runs, the replacement will work correctly
• For merged table cells, multiple (row, col) coordinates point to the same cell — use the structure command to identify which coordinates are primary vs duplicates (marked as "merged")
• When filling forms from another document, first extract the data, then map fields to cell coordinates
• Always verify the output by reading back key cells after editing