spb/ultra-sharp-agent-skills Public

1---2name: processing-docx3description: Creates, reads, and modifies Word documents (.docx, .dotx) with python-docx — paragraphs, headings, tables, images, styles — and reads them as Markdown via pandoc. Use when the user asks to create, open, read, edit, or fix a Word document, mentions .docx/.dotx files, or wants a report, memo, letter, or template in Word format. Do not use for PDFs, spreadsheets, Google Docs, or Markdown files.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Processing DOCX1213## When to use / when NOT to use14- **Use for:** creating, reading, or modifying `.docx` and `.dotx` files — text, headings, tables, images, styles.15- **Do NOT use for:** PDFs, spreadsheets, Google Docs (different API), or plain Markdown/text files.1617## Quick reference1819Default library: **python-docx**. Reading: **pandoc** first, python-docx as fallback. Escape hatch: unzip + edit `word/document.xml` + rezip for what python-docx can't do (tracked changes, comments).2021**Create:**22```python23from docx import Document24doc = Document()25doc.add_heading("Quarterly Report", level=1)26doc.add_paragraph("Revenue grew 12% quarter over quarter.")27t = doc.add_table(rows=2, cols=2)28t.style = "Table Grid"29t.rows[0].cells[0].text = "Region"30doc.save("report.docx")31```3233**Read (pandoc default, python-docx fallback):**34```bash35pandoc -t markdown report.docx -o report.md36```37```python38# fallback if pandoc is missing39from docx import Document40text = "\n".join(p.text for p in Document("report.docx").paragraphs)41```4243**Modify:**44```python45from docx import Document46doc = Document("report.docx")47for p in doc.paragraphs:48    if "12%" in p.text:49        for run in p.runs:50            run.text = run.text.replace("12%", "14%")51doc.save("report.docx")52```5354## Workflow551. Classify the task: create / read / modify.562. Read: try `pandoc -t markdown file.docx`; if pandoc is not installed, fall back to python-docx text extraction (note: fallback loses images and most formatting fidelity).573. Create/modify with python-docx. When editing, reuse the document's existing styles (`doc.styles`) instead of hardcoding fonts.584. For tracked changes or comments, python-docx cannot help: unzip the `.docx`, edit `word/document.xml`, rezip with the original file layout (see recipes).595. Validate: re-open the saved file with `Document(path)` — if it raises, fix before delivering. Confirm expected paragraph/table counts.606. Report the output path and what changed.6162## Edge cases & failure modes63- **python-docx missing** → `pip install python-docx`. **pandoc missing** → `brew install pandoc` (macOS) / `apt-get install pandoc`; or use the python-docx fallback.64- **Corrupt / not a zip** → `Document()` raises `PackageNotFoundError`; report the file is not a valid docx, stop.65- **Password-protected document** → python-docx cannot decrypt; ask the user for an unprotected copy.66- **`.doc` (legacy binary)** → not supported by python-docx; convert first: `soffice --headless --convert-to docx file.doc`.67- **Large documents (hundreds of pages)** → python-docx loads the whole XML tree; fine to ~10k paragraphs, but prefer targeted XML edits for bulk find-and-replace across huge files.6869## References70Deeper recipes (styles, images, headers/footers, find-and-replace across runs, XML escape hatch, conversion, gotchas): see [references/recipes.md](references/recipes.md).71