build-office-docs

name	build-office-docs
description	Generates and edits Office documents (DOCX/PPTX) programmatically from data or templates, including styled reports, tables, headers/footers, tracked changes, and slide decks.
when_to_use	When the user asks to create or edit a Word document or PowerPoint deck — generate a report, fill a DOCX/PPTX template, mail-merge data into letters/memos, build slides from an outline, or apply tracked-changes edits to an existing .docx.

When to Use

Trigger this skill when the task produces or modifies a .docx or .pptx file:

• Generate a Word report/letter/memo from data or a written outline.
• Fill a DOCX/PPTX template that has {{placeholder}} fields or named shapes.
• Mail-merge one template over a row set (one output file per row, or one file with repeated sections).
• Build a slide deck from a structured outline (title + bullets + notes per slide).
• Edit an existing .docx: find-replace, insert/restyle tables, add headers/footers/page numbers, or apply tracked changes.

Do NOT use this for: plain .txt/.md/.csv output, PDFs (use a PDF/HTML-to-PDF path), or .doc/.ppt legacy binary formats (convert to OOXML first via LibreOffice soffice --headless --convert-to docx).

Steps

1. Classify the job along two axes before writing code:

   • Format: docx (Word) vs pptx (PowerPoint). Decide from the request, not the extension alone.
   • Mode: from-scratch (build a new file) · template (fill placeholders in an existing file) · edit-existing (mutate a real document, preserving its styles). Print the chosen {format, mode} before proceeding — the library and approach differ per cell.

2. Pick the library by {format, mode}. Do not invent a new dependency if one is already in the repo:

   • docx, from-scratch / edit-existing → python-docx.
   • docx, template with {{fields}}/Jinja loops → docxtpl (renders Jinja2 inside a real .docx, keeps styles).
   • pptx, any mode → python-pptx.
   • Low-level changes these libraries can't express (tracked changes w:ins/w:del, custom XML, content controls, theme colors) → edit the OOXML directly: a .docx/.pptx is a zip of XML parts (word/document.xml, ppt/slides/slideN.xml). Unzip, edit XML via lxml, re-zip. Confirm the package is installed (pip show python-docx docxtpl python-pptx); install into the project env, not globally, if missing.

3. DOCX — from scratch (python-docx):

   • Structure with real styles, not manual formatting: doc.add_heading(text, level=N), doc.add_paragraph(text, style='List Bullet'|'List Number'). Reuse doc.styles / a base template (Document('template.docx')) so output inherits the org's fonts and theme.
   • Tables: t = doc.add_table(rows, cols), set t.style = 'Light Grid Accent 1' (must be a style that exists in the doc, else it errors). Cell styling lives on the run inside the cell paragraph: cell.paragraphs[0].add_run(text).bold = True; widths need tblLayout fixed (t.autofit = False + set each cell.width).
   • Headers/footers/page numbers: section.header / section.footer; a page-number field requires a fldSimple/w:instrText PAGE XML run (python-docx has no helper — inject the XML via run._r.append(...)).
   • Images: doc.add_picture(path, width=Inches(...)); missing files raise, so check the path first.

4. DOCX — template fill & mail-merge (docxtpl):

   • Author the template with Jinja in real Word text: {{ customer_name }}, {% for row in items %}...{% endfor %} (use {%tr ... %} to repeat table rows, {%p ... %} to repeat paragraphs). Tag names must match the context dict keys exactly.
   • Render: tpl = DocxTemplate('tpl.docx'); tpl.render(context); tpl.save(out).
   • Mail-merge = loop the data rows: render one output per row → out_{i}.docx (or _{key}.docx), OR pass a list into one template and use a {%tr%}/{%p%} loop for a single combined file. Decide which the user wants up front.
   • Insert images/rich runs via tpl.new_subdoc() / InlineImage, not raw strings, so styling survives.

5. PPTX (python-pptx):

   • Start from Presentation('template.pptx') to inherit master/layouts; Presentation() alone gives the default theme only.
   • Per slide: pick a layout (prs.slide_layouts[idx]), slide = prs.slides.add_slide(layout), then fill named placeholders by index/type (slide.placeholders[0].text = title) — do not assume placeholder 1 is always the body; inspect [ph.placeholder_format.idx for ph in slide.placeholders].
   • Bullets: write into the body placeholder's text_frame, one paragraph per bullet, set paragraph.level for indent.
   • Speaker notes: slide.notes_slide.notes_text_frame.text = notes.
   • Charts/tables: slide.shapes.add_chart(...) with a CategoryChartData, or add_table(rows, cols, x, y, w, h).

6. Edit-existing without nuking styles: open the real file, mutate only target nodes. For find-replace in python-docx, replace at the run level (text can be split across runs — naive paragraph.text = ... drops formatting); join/split runs carefully or use a known replace helper.

7. Tracked changes are not in python-docx's API — do it at the XML layer: an insertion is a <w:ins w:author w:date> wrapping the new run; a deletion wraps the old run in <w:del> with the text in <w:delText>. Set author/date attributes. Verify Word shows them under Review → Track Changes after opening.

8. Render to the requested path, then validate (step into ## Verify) before declaring done. Report the absolute output path and confirm the file opens.

Common Errors

• Corrupt file after manual XML edits — re-zipping with wrong compression/structure, missing [Content_Types].xml, or a stray byte breaks the package and Word says "needs repair". Always round-trip through zipfile (preserve all parts), and re-open with the library after writing to catch corruption early.
• Style does not exist → exception or silent no-op. t.style = 'Some Style' / add_paragraph(style=...) only works if that style is defined in the document. Build from a template that contains the style, or add the style definition first. Style names are case- and space-sensitive.
• Fonts/styles "not embedded" → output looks wrong on another machine. OOXML references fonts by name; it does not embed them. If a specific font is required, embed it (<w:embedRegular> font part) or restrict to fonts the consumer has. Theme colors only resolve if the theme part is present (another reason to start from a real template).
• Merge-field / placeholder mismatch. A {{tag}} with no matching context key renders empty or raises (jinja2.UndefinedError); a key with no tag is silently ignored. Diff the template's tag set against the context dict keys before rendering. Word sometimes splits {{ tag }} across runs so docxtpl can't see it — keep each tag typed in one run (retype it cleanly in Word).
• find-replace drops formatting because Word stores one logical word across multiple <w:r> runs. Replacing paragraph.text collapses runs and loses bold/italic/links. Operate run-by-run or use a run-aware replacer.
• PPTX placeholder index assumption — layouts differ; index 1 is not always the content body. Always enumerate slide.placeholders and match by placeholder_format.type/idx.
• add_picture/template path is relative and the working dir differs at run time → FileNotFoundError. Use absolute paths.
• Tracked changes invisible because w:author/w:date are missing or the run wasn't wrapped in w:ins/w:del — Word then shows the edit as a normal change. Confirm the wrapping nodes and attributes exist.

Verify

A generated/edited Office file is done only when ALL hold:

• The file exists at the reported absolute path and has non-trivial size (> a few KB; a 0-byte or tiny file means the write failed).
• It is a valid OOXML package: unzip -l <file> lists parts including [Content_Types].xml and word/document.xml (docx) or ppt/presentation.xml (pptx) — no zip error.
• It re-opens with the library without exception: Document(out) (docx) or Presentation(out) (pptx) loads, and a spot-check reads back expected content (a heading's text, a known cell value, slide count == expected).
• For templates/mail-merge: no {{ / }} / {% literals remain in the output (unzip -p <file> word/document.xml | grep -c '{{' returns 0), and one output file exists per data row when per-row mode was chosen.
• For tracked changes: word/document.xml contains the expected <w:ins>/<w:del> nodes with author+date; opening in Word shows them under Review.
• If a specific font/style/theme was requested, it is present (style name resolves; theme/font part exists in the zip).

If validation cannot run (no Word/LibreOffice available and the library re-open is the only check), state that the file passed structural+library validation but was not opened in a real Office client.