docx skill

Purpose: Give the agent a deterministic, script-first way to create, edit, and convert Microsoft Word .docx files so it does not have to re-derive low-level OOXML constructs (page sizes, tables, tracked changes, comment markers, image embeddings, template substitution) on every task. Writing .docx by hand through docx-js or python-docx calls is feasible but error-prone; the scripts here encode the practical knowledge and make the common operations a single command.

1. Red Flags (Anti-Rationalization)

STOP and READ THIS if you are thinking:

• "I'll just assemble the docx inline with docx-js calls, the scripts are overkill." → WRONG. md2docx.js already handles page size, numbering, dual-width tables, and image alt-text — regressions from hand-rolled code usually show as silently broken tables or images on Word for Windows.
• "I can skip docx_fill_template.py's run-merge pass and just regex-replace {{placeholder}}." → WRONG. Word and Google Docs fracture a single placeholder across multiple <w:r> siblings after spell-check or autocorrect; a naïve regex won't match and the placeholder will ship unfilled.
• "For tracked changes I'll just delete every <w:del> block." → WRONG. That loses author attribution and breaks paragraph-level delete markers. Use docx_accept_changes.py which drives LibreOffice's own accept dispatcher.
• "The smart-quote entity rewrite in office/unpack.py is ugly, I'll turn it off." → WRONG. Different Word builds round-trip UTF-8 quotes inconsistently. Keeping them as ’ etc. on unpack and reversing on pack makes edits deterministic.
• "I'll just regex-replace \| in OOXML to extract or modify text." → WRONG. Raw XML regex operates on serialised bytes and breaks namespace prefixes, entity encoding, and split-run anchors. Use docx_replace.py (anchor-and-action surgical edit) which works at the lxml element level after run canonicalisation.
• "It's an Obsidian note but it's still Markdown — I'll just run it through md2docx.js." → WRONG. md2docx.js exits 0 and writes a valid .docx that is missing content. Measured on a real vault note: the YAML frontmatter is stripped unconditionally (so participants, which live only there, vanish), ![[embed]] and [[wikilink]] reach marked as text tokens and land in the document as literal ![[…]] strings, and a bare space in an image path also lexes as text — every vault path has spaces. Exit 0 guarantees nothing here. Use md2docx.js --obsidian (or obsidian2md.js first).
• "The note has no ![[embeds]], so plain md2docx.js is fine." → WRONG if it has frontmatter. D1 fires on every note: the frontmatter is dropped silently and metadata that lives nowhere else goes with it.
• "I need to edit a .docx and the docx2md → md2docx round-trip loses styling." → Use docx_replace.py --replace instead. It operates at run level, preserving bold/italic/colour/numbering. Round-trip through markdown is lossy: inline formatting, list numbering schemas, and table borders all flatten.
• "The doc has $x^2$ in it, md2docx.js will just write it as text and that's fine." → WRONG before TASK 031. $…$/$$…$$ used to reach the document as literal characters, exit 0, no warning — the same silent-loss class as the Obsidian defects above. As of TASK 031, math is on by default: it converts to a native OOXML <m:oMath> object, editable in Word like any equation authored with the equation editor. Only --no-math restores the old literal-text behaviour.

2. Capabilities

• Surgical anchor-and-action edit of a live .docx (no template required) via docx_replace.py — find a text anchor and --replace TEXT / --insert-after PATH / --delete-paragraph without a lossy docx2md → md2docx round-trip. Run-level formatting (bold, italic, colour, numbering) is preserved. --insert-after automatically relocates images, charts, OLE objects, SmartArt diagrams, and numbered/bulleted lists from the MD source into the base document (docx-6.5 + docx-6.6 v2 relocators, 2026-05-12). Honest scope: --replace requires the anchor to fit within a single <w:t> after run-merge (cross-run anchors not supported, R10.a); --insert-after and --delete-paragraph work at paragraph granularity. Anchor not found → exit 2 AnchorNotFound; last-paragraph delete refused → exit 2 LastParagraphCannotBeDeleted.
• Convert Markdown to .docx with headings, lists, tables, images, and optional mermaid diagrams via md2docx.js.
• Render inline $…$ and display $$…$$ math as native OOXML <m:oMath> objects via md2docx.js — on by default, editable in Word like an equation authored with its own equation editor, not a raster image. Pipeline: KaTeX renders TeX to MathML in-process, mathml2omml converts to OMML, spliced into the paragraph as a fresh object per occurrence. A standalone $$…$$ alone between blank lines (or the sole content of a table cell) gets a dedicated centred paragraph; a 4-column table whose 1st/3rd cells are blank — the Pandoc | | $$…$$ | | (N) | equation-with-number convention — gets asymmetric column widths so the formula isn't clipped to 1/4 of the page width. A formula that fails to render degrades to its literal source text plus a stderr warning (never a silent drop); --strict-math turns that into a hard exit 1 instead. --no-math restores pre-TASK-031 literal-text behaviour exactly. Honest scope: no Word-native automatic equation numbering (a source document's own numbers, sitting outside the $$…$$ delimiters, convert unchanged); math inside **bold**/*italic*/a link still renders as a real object but without that styling; math in an image's alt text renders as literal text (the ImageRun.altText field has nowhere to splice a run into).
• Convert an Obsidian vault note to .docx in one command via md2docx.js --obsidian [--vault-root DIR], or to clean CommonMark via obsidian2md.js (both share _obsidian_lib.js). Closes four measured silent-loss defects: YAML frontmatter dropped, ![[embed]] and [[wikilink]] unrecognised, and spaces in image paths. Frontmatter is re-emitted as a two-column table by default (--frontmatter table|render|strip) — a GFM table, so it goes through the same table token path as every other table and carries the identical borders and header shading. Attachments resolve in Obsidian's own order (.obsidian/app.json → note directory → literal path → NFC-folded vault-wide index); callouts (> [!warning] Title), ==highlight==, %%comment%%, #inline-tags, and - [ ] task boxes are normalised; fenced/indented/inline code is masked and passes through byte-identical, so a note documenting Obsidian syntax is not rewritten. Opt-in --transclude inlines ![[Note]] with cycle protection (depth ≤ 3, visited-set) and confines the target to the vault — inlining text from outside it would be an arbitrary-file read driven by a note somebody else wrote. Missing attachment → placeholder + stderr warning (exit 0), or exit 8 AssetNotFound under --strict-assets. Honest scope: math ($…$) still reaches the document as text (backlog docx-11); a |300 width hint is an upper bound and never upscales, unlike Obsidian itself; .webp is named as a file rather than embedded, because the docx image layer cannot carry it; and an indented code block nested inside a list is treated as list content, so Obsidian syntax inside one is still rewritten.
• Convert HTML / web archives to .docx via html2docx.js — accepts .html/.htm, Chrome .mhtml/.mht, and Safari .webarchive (sub-resources extracted to a temp dir). Confluence, GitLab wiki, and CMS chrome (ARIA-role-tagged headers/sidebars/footers, namespaced <ac:*> macros, tablesorter <button> wrappers) is stripped automatically before walking. Inline SVG diagrams (drawio/mermaid/PlantUML) are rastered to PNG via a two-tier renderer: Tier 1 = headless Chrome / Chromium / Edge / Brave (auto-detected from conventional install paths or HTML2DOCX_BROWSER) gives pixel-perfect CSS layout including foreignObject labels and word-wrap; Tier 2 = @resvg/resvg-js fallback for hosts without a browser, with foreignObject → SVG <text> conversion that preserves drawio's centring math, synthesises a viewBox on canvas-clipped diagrams (5% expansion absorbs drawio's edge-overshoot artifact), and word-wraps long Cyrillic/Latin labels at the wrapper's width:Npx so text fits inside its box. --reader-mode opt-in: stripped CMS chrome via a curated candidate list (#main-content, .entry, .post-content, article) with per-candidate min-text filter — useful for browser-saved news / blog pages where Confluence-priority selectors fall through to <body>.
• Extract .docx content back to Markdown preserving tables, lists, and embedded images via docx2md.js. Comments and tracked changes (which mammoth strips) are pulled into a JSON sidecar (<output>.docx2md.json) — useful for contract audits where the audit trail must accompany the converted markdown. Footnotes/endnotes are converted to pandoc-style [^fn-N] / [^en-N] markers with definitions appended at the end. Text Word hides (<w:vanish/>, set directly or through a character/paragraph style) is dropped, because Word neither shows nor prints it; --keep-hidden-text keeps it. Schema versioned (v: 1); the sidecar's unsupported field reports counts of revision types not yet captured (rPrChange, pPrChange, moveFrom, moveTo, cellIns, cellDel) so callers know what was lost. Opt-out via --no-metadata (skip sidecar) and --no-footnotes (skip pandoc conversion). Sidecar is not written when the source has no comments, no revisions, and zero unsupported counts — clean docs stay clean.
• Fill .docx templates containing {{placeholder}} or {{nested.key}} markers from a JSON payload with safe run-merging.
• Accept all tracked changes in a .docx via headless LibreOffice without leaving artefacts in the user's profile.
• Unpack and repack .docx archives for raw OOXML editing, with smart-quote entity round-tripping and run canonicalisation.
• Structurally validate a .docx: relationships, content types, tracked-change/<w:delText> integrity, comment marker pairing, package-layout allow-list (every ZIP entry must live under [Content_Types].xml, _rels/, word/, docProps/, or customXml/ per ECMA-376 §11.3.10 — catches scratch-file leaks that Word refuses to open while LibreOffice silently tolerates), and optional XSD binding. With --strict, the package-layout warning is promoted to exit 1.
• Reject password-protected and legacy .doc (CFB-container) inputs early with a clear remediation message (exit 3) instead of a BadZipFile traceback.
• Detect macro-enabled inputs (.docm, with vbaProject.bin) and warn when the chosen output extension would silently drop the macros (docm → docx).
• Render any .docx/.docm/.pdf (or peer-skill .xlsx/.pptx) into a single PNG-grid preview via preview.py (LibreOffice + Poppler).
• Emit failures as machine-readable JSON to stderr with --json-errors (uniform across all four office skills).
• Set or remove a password on a .docx/.xlsx/.pptx (MS-OFB Agile, Office 2010+) via office_passwd.py — three modes: --encrypt PASSWORD, --decrypt PASSWORD, --check (exit 0 encrypted / 10 clean / 11 missing).
• Insert a Word review comment anchored on a text substring via docx_add_comment.py — wires <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> markers, appends to word/comments.xml, and patches [Content_Types].xml + relationships. Supports threaded replies (--parent N) via <w15:commentEx w15:paraIdParent=…> in commentsExtended.xml; reply-to-reply chains are flattened to the conversation root to match Word's review-pane render. Multi-paragraph bodies via \n in --comment are split into separate <w:p> per ECMA-376 §17.13.4.2. Opt-in library mode (--unpacked-dir DIR) operates in-place on an already-unpacked tree (skips unpack/pack/encryption-check) — not reentrant: do not run two processes against the same tree concurrently, no file locking. Malformed OOXML side-parts surface as MalformedOOXML envelope (not a traceback). See references/add-comment-howto.md for verification steps and §6 troubleshooting for failure modes.
• Merge N .docx files into one via docx_merge.py (VDD iter-2 real-world hardened). Appends body content + styles + numbering + media + relationships into the first input (base), with full reference relocation: image rIds renumbered, r:embed/r:link/r:id in body remapped, <w:bookmarkStart/End w:id> bumped past base's max, <w:abstractNum> / <w:num> shifted with <w:numId w:val> body refs rewritten, missing Default Extension entries pulled into [Content_Types].xml. Strips paragraph-level <w:sectPr> from extras (their header/footer references would dangle). Inserts new <w:abstractNum> BEFORE first <w:num> per ECMA-376 §17.9.20 schema-order. Honest scope (still not merged, warned when extras have content): footnotes / endnotes / headers / footers / comments.

3. Execution Mode

• Mode: script-first.
• Why this mode: Each operation is a small, deterministic CLI wrapping a specific OOXML-aware library. Inline assembly in the agent's text is slower and regresses on details (page size, DXA units, namespace ordering). Scripts also make the skill reusable from any shell environment.

4. Script Contract

• Commands:
  • node scripts/md2docx.js INPUT.md OUTPUT.docx [--header "TEXT"] [--footer "TEXT"] [--page-size A4|Letter] [--landscape] [--margins T,R,B,L] [--no-math] [--strict-math] — math ($…$/$$…$$ → native <m:oMath>) is on by default; --no-math disables it entirely (literal text, pre-TASK-031 behaviour); --strict-math exits 1 on the first formula KaTeX cannot render instead of the default degrade-to-literal-text-plus-warning.
  • node scripts/md2docx.js INPUT.md OUTPUT.docx --obsidian [--vault-root DIR] [--frontmatter table|render|strip] [--lang ru|en|auto] [--links text|italic] [--inline-tags strip|keep] [--transclude] [--strict-assets] — the one-command Obsidian route. --vault-root defaults to the nearest ancestor of the note containing .obsidian/, else the note's own directory. Every Obsidian flag requires --obsidian; using one without it exits 1 with --vault-root requires --obsidian (exit 1 is md2docx.js's code for every usage error, unchanged since TASK 019). Flag order is irrelevant. --strict-assets exits 8, in plain text — md2docx.js has no --json-errors.
  • node scripts/obsidian2md.js INPUT.md OUTPUT.md [--vault-root DIR] [--frontmatter table|render|strip] [--lang ru|en|auto] [--links text|italic] [--inline-tags strip|keep] [--transclude] [--strict-assets] [--json-errors] — Obsidian-flavoured Markdown → CommonMark, no OOXML involved. Defaults: --frontmatter table, --lang auto (reads the note's lang: key, else en), --links text, --inline-tags strip. Exit codes: 0 success, 1 I/O, 2 invalid argument / usage, 6 same-path self-overwrite refused (SelfOverwriteRefused), 8 attachment not found under --strict-assets (AssetNotFound). --json-errors emits the standard {v:1, error, code, type, details} envelope on every non-zero path. Output is idempotent: a second run over the same input is byte-identical. A CommonMark document with no Obsidian syntax passes through byte-identical.
  • node scripts/docx2md.js INPUT.docx OUTPUT.md [--metadata-json PATH] [--no-metadata] [--no-footnotes] [--keep-hidden-text] [--json-errors]
  • node scripts/html2docx.js INPUT OUTPUT.docx [--header "TEXT"] [--footer "TEXT"] [--reader-mode] [--json-errors] — INPUT may be .html/.htm, .mhtml/.mht, or .webarchive; sub-resources in archives are extracted to a temp dir automatically (cleaned up on exit incl. SIGINT/SIGTERM). --reader-mode swaps the article-root candidate list for a CMS/blog-specific one (#main-content/.entry/.post-content/article with per-candidate min-text filter; bare <main> deliberately omitted as it wraps whole-site chrome on news sites). Override SVG renderer with HTML2DOCX_BROWSER=/path/to/chrome or set it to a non-existent path to force the resvg-js fallback for CI determinism. Set HTML2DOCX_ALLOW_NO_SANDBOX=1 only inside a trusted CI container — default leaves Chrome's sandbox enabled.
  • python3 scripts/docx_fill_template.py TEMPLATE.docx DATA.json OUTPUT.docx [--strict]
  • python3 scripts/docx_accept_changes.py INPUT.docx OUTPUT.docx [--timeout 120]
  • python3 scripts/office/unpack.py INPUT.docx OUTDIR/ [--no-pretty] [--no-escape-quotes] [--no-merge-runs]
  • python3 scripts/office/pack.py INDIR/ OUTPUT.docx [--no-unescape-quotes] [--no-condense]
  • python3 scripts/office/validate.py INPUT.docx [--strict] [--json] [--schemas-dir PATH] [--compare-to ORIGINAL.docx]
  • python3 scripts/preview.py INPUT OUTPUT.jpg [--cols 3] [--dpi 110] [--gap 12] [--padding 24] [--label-font-size 14] [--soffice-timeout 240] [--pdftoppm-timeout 60]
  • python3 scripts/office_passwd.py INPUT [OUTPUT] (--encrypt PASSWORD | --decrypt PASSWORD | --check) — pass - as PASSWORD to read it from stdin.
  • python3 scripts/docx_add_comment.py INPUT.docx OUTPUT.docx --anchor-text TEXT --comment BODY [--author NAME] [--initials AB] [--date ISO] [--all]
  • python3 scripts/docx_add_comment.py INPUT.docx OUTPUT.docx --parent N --comment BODY [--author NAME] — reply to comment N (inherits its anchor range; threads via commentsExtended.xml).
  • python3 scripts/docx_add_comment.py --unpacked-dir DIR --anchor-text TEXT --comment BODY [...] — library mode: edit an already-unpacked tree in-place (combine with --parent to add a reply over the same tree).
  • python3 scripts/docx_replace.py INPUT.docx OUTPUT.docx --anchor TEXT (--replace TEXT | --insert-after PATH_OR_DASH | --delete-paragraph) [--all] [--unpacked-dir DIR] [--scope=LIST] [--json-errors] — Tier B (script-first); positional INPUT OUTPUT; --anchor TEXT is always required; exactly one of --replace/--insert-after/--delete-paragraph is required (mutex). --all replaces/acts on every match instead of first. --unpacked-dir DIR operates on an already-unpacked tree in-place (library mode — skips unpack/pack/encryption-check). --insert-after - reads the markdown body from stdin. --scope=LIST (docx-6.7) restricts anchor-search to a subset of OOXML parts: comma-separated body, headers, footers, footnotes, endnotes, all (default: all). Example: --scope=body limits edits to word/document.xml, leaving header/footer boilerplate untouched. Order within the requested set is deterministic (document → headers → footers → footnotes → endnotes). Exit codes: 0 success, 1 I/O or OOXML error, 2 anchor-not-found / last-paragraph-delete refused / invalid --scope value, 3 encrypted/password-protected input, 6 same-path self-overwrite refused, 7 post-validate failure. --json-errors emits failures as {v:1, error, code, type, details} JSON on stderr (cross-5 envelope parity). Honest scope: --replace anchor must fit within a single <w:t> after run-merge; --insert-after converts markdown to OOXML via md2docx.js (requires Node.js in PATH).
  • python3 scripts/docx_merge.py OUTPUT.docx INPUT1.docx INPUT2.docx [...] [--page-break-between] [--no-merge-styles]
  • All scripts above accept --json-errors to emit failures as a single line of JSON on stderr ({v, error, code, type?, details?}). The schema version v is currently 1; argparse usage errors are routed through the same envelope (type:"UsageError").
• Inputs: positional paths only; optional flags per command.
• Outputs: a single file at the named output path; office/unpack.py produces a directory tree; office/validate.py prints a report (or JSON with --json). docx2md.js additionally creates <stem>_images/ next to the Markdown output when the document has embedded images.
• Failure semantics: non-zero exit on missing input, invalid JSON, unresolved placeholders (with --strict), unreadable ZIP, or soffice errors. Error detail goes to stderr.
• Idempotency: repeated runs with the same inputs produce equivalent output files (byte-exact for the XML parts after pretty-print and entity normalisation). docx_accept_changes.py is idempotent on an already-accepted document. Exception: office_passwd.py --encrypt is intentionally non-deterministic — Office encryption uses a fresh random salt per run, so the encrypted bytes differ each time even with the same password. The decrypted output, however, is byte-equal to the pre-encryption input (lossless round-trip).
• Dry-run support: not applicable; operations are file-to-file and reversible by re-running.

5. Safety Boundaries

• Allowed scope: only the input/output paths named on the command line and, for Python scripts, modules under scripts/. Never modify files the user did not name.
• Read scope, --obsidian / obsidian2md.js only (containment is compared on realpath, not on path strings — a directory symlink shipped inside a vault walks straight through a prefix check): resolving an Obsidian note additionally reads (never writes) files the command line did not name — attachments under the vault root, <vault>/.obsidian/app.json, and, under --transclude, sibling notes. The vault root is --vault-root, else the nearest ancestor of the note containing .obsidian/, else the note's directory. .obsidian/, .git/, node_modules/ and .trash/ are never walked, directory symlinks are never followed, and the index is built once per run. attachmentFolderPath is untrusted input that travels with a vault: an absolute value, or one resolving outside the vault, is refused with a warning. A note may still name an absolute path in its own link — the same capability plain Markdown ![](/abs/path.png) already has, and it is not confined.
• Default exclusions: never overwrite the input in place unless the same path is also passed as output; never fetch remote images silently; never install npm/pip packages globally.
• Destructive actions: docx_accept_changes.py rewrites the destination; always use a distinct output path unless the user explicitly asks for in-place replacement. office/pack.py overwrites the destination archive.
• Optional artifacts: the office/schemas/ directory is optional; office/validate.py runs structural checks without it and only warns about missing XSDs unless --strict.

6. Validation Evidence

• Local verification:
  • cd skills/docx/scripts && npm install — installs docx, marked, mammoth, turndown, image-size, turndown-plugin-gfm into scripts/node_modules/.
  • python3 -m venv .venv && source .venv/bin/activate && pip install -r scripts/requirements.txt — installs python-docx, lxml, defusedxml.
  • node scripts/md2docx.js examples/fixture-simple.md /tmp/out.docx && unzip -l /tmp/out.docx | grep word/document.xml — exits 0 and lists the document part.
  • node scripts/docx2md.js /tmp/out.docx /tmp/back.md && test -s /tmp/back.md — round-trips non-empty Markdown. On a docx with comments / tracked changes, also writes /tmp/back.docx2md.json (schema v:1); on a docx with footnotes/endnotes, the markdown gets pandoc-style [^fn-N] markers + definitions block at the end. See references/docx2md-sidecar.md for the full schema and --metadata-json / --no-metadata / --no-footnotes flags. Same-path (docx2md.js foo.docx foo.docx) is refused with exit 6 (SelfOverwriteRefused) so the input is never destroyed.
  • node scripts/md2docx.js examples/fixture-obsidian-vault/note.md /tmp/obs.docx --obsidian --vault-root examples/fixture-obsidian-vault && unzip -l /tmp/obs.docx | grep -cE 'word/media/.*\.(png|jpg)' — the committed mini-vault note: exit 0, 5 embedded images, frontmatter inside a <w:tbl>. Full acceptance set (A1-A16) in scripts/tests/test_obsidian2md.py, 90 cases.
  • node scripts/md2docx.js examples/fixture-math.md /tmp/math.docx && unzip -p /tmp/math.docx word/document.xml | grep -o '<m:oMath' | wc -l — exit 0, ≥4 native math objects. test_md2docx_math.py (26 cases).
  • python3 scripts/office/validate.py /tmp/out.docx — exits 0, prints OK or only warnings.
  • python3 scripts/office/unpack.py /tmp/out.docx /tmp/unpacked && python3 scripts/office/pack.py /tmp/unpacked /tmp/repack.docx && unzip -p /tmp/repack.docx word/document.xml | head -c 100 — unpack/pack round trip.
  • python3 scripts/docx_add_comment.py /tmp/out.docx /tmp/commented.docx --anchor-text "Quarterly" --comment "Verify this number" --author "QA Bot" && python3 -m office.validate /tmp/commented.docx — adds a Word comment anchored on the substring; output validates and contains a <w:comment> part. See references/add-comment-howto.md for the full verification protocol.
  • python3 scripts/docx_merge.py /tmp/merged.docx /tmp/out.docx /tmp/out.docx --page-break-between && python3 -m office.validate /tmp/merged.docx — merges N inputs (here, two copies of out.docx) with a hard page break between them; output validates clean.
• Expected evidence: /tmp/out.docx, /tmp/back.md, /tmp/unpacked/ tree, /tmp/repack.docx. All reproducible from examples/fixture-simple.md.
• CI signal: python3 ../../.claude/skills/skill-creator/scripts/validate_skill.py skills/docx — exits 0 when the skill conforms to the Gold Standard (frontmatter, required sections, non-empty examples).

7. Instructions

Use graduated language: steps marked MUST are safety-critical; the rest are behavioural defaults with their rationale.

7.1 Select the right script before touching low-level APIs

1. Look up the task in §10 Quick Reference first. If a script exists, run it — it captures accumulated OOXML knowledge that inline code tends to get wrong.
2. Drop to docx-js or python-docx calls only when the user's requirement genuinely is not covered (e.g. inserting a custom content control, manipulating a specific style's inheritance chain).

7.2 Install dependencies locally

1. MUST run bash scripts/install.sh once. It creates scripts/.venv/ and scripts/node_modules/ locally (nothing installed globally), prints a warning for any missing system tool, runs a smoke-test of the documented commands before declaring success, and is idempotent.
2. Invocation — python3 is safe. The Python CLIs self-bootstrap into scripts/.venv: python3 scripts/X.py … and ./.venv/bin/python scripts/X.py … are equivalent — on a host where python3 is not the venv (pyenv / conda / system Python), the script re-execs itself into scripts/.venv. If the venv is missing, you get a run: bash scripts/install.sh hint instead of a raw ModuleNotFoundError. (Node CLIs resolve scripts/node_modules, also local.)
3. External system tools (checked by install.sh, installed manually per project plan §3.3 "внешние инструменты — не бандлятся"):
   • LibreOffice (soffice) — required by docx_accept_changes.py. macOS: brew install --cask libreoffice. Debian: sudo apt install libreoffice --no-install-recommends. Fedora: sudo dnf install libreoffice. Commands that need it fail with a clear error until it's installed.

7.3 Creating .docx from Markdown

1. Prefer md2docx.js over hand-writing new Document({...}).
2. Page size / orientation / margins are exposed as flags — default US Letter portrait (backward-compatible): --page-size A4|Letter, --landscape, --margins T,R,B,L (dxa, each value optionally mm-suffixed). Content width, tables, and images/Mermaid diagrams all auto-derive from the chosen page, so they never overflow A4 — no manual word/document.xml patching needed. Example: node scripts/md2docx.js report.md report.docx --page-size A4.
3. For headers/footers use --header "…" / --footer "…". Multi-line headers are a single string with \n — md2docx.js splits on the newline.

7.4 Extracting text from .docx to Markdown

1. Use docx2md.js for GFM output with tables preserved. If the document contains images, a sibling <stem>_images/ directory is created — tell the user so they know to ship it alongside the Markdown.
2. For docs that carry comments or tracked changes, the converter writes a JSON sidecar <stem>.docx2md.json next to the Markdown. Tell the user to ship the sidecar alongside the markdown if the audit trail matters; the sidecar's absence on a clean doc is a feature, not a missing artefact. Field semantics + the unsupported counters are documented in references/docx2md-sidecar.md.
3. For docs with footnotes/endnotes, the markdown body gets pandoc-style [^fn-N] / [^en-N] markers and definitions appended at the end. Pass --no-footnotes if downstream tooling can't parse pandoc syntax.
4. Hidden text is dropped by default, and stdout reports Dropped N hidden run(s). When it does, tell the user. Pass --keep-hidden-text when the hidden part is the point: template instructions, translation-tool markup, auditing what a document conceals.
5. MUST NOT invoke docx2md.js with the same input and output path — the cross-7 H1 guard exits 6 (SelfOverwriteRefused), but better to never tempt it.
6. For plain text without any formatting, pandoc -t plain is a valid alternative but external — document this choice to the user rather than silently switching tools.

7.5 Filling a template

1. MUST ensure the template contains placeholders in the exact form {{key}} or {{nested.key}}. Spaces inside the braces ({{ key }}) are tolerated; anything else ([key], ${key}, <%=key%>) is not recognised.
2. Provide data.json as an object at the top level.
3. Pass --strict when the template must be fully resolved (legal documents, customer-facing letters). Without --strict, unresolved placeholders remain in the output and are listed on stderr.

7.6 Accepting tracked changes

1. docx_accept_changes.py requires LibreOffice. Check _soffice.py locates it before telling the user it "just works" — on some CI images LibreOffice is absent.
2. Output must be a new path; do not overwrite the input unless asked. Even then, prefer an intermediate file and move on success.
3. LibreOffice 26.2 limitation: the CLI macro:/// dispatch this script relies on is unreliable on 26.2 (dropped on cold profiles while soffice exits 0). The script self-verifies: if revision marks survive, it removes the bogus output and exits 1 with AcceptChangesVerificationError — tell the user to accept the changes in a desktop Word/LibreOffice session or use LibreOffice 25.x. It never silently hands back an unaccepted copy.

7.7 Raw OOXML editing

1. python3 scripts/office/unpack.py doc.docx work/ first — this pretty-prints, merges adjacent runs, and entity-encodes smart quotes, so editing is safe.
2. Edit XML under work/word/, work/ppt/, or work/xl/ (docx/pptx/xlsx respectively).
3. python3 scripts/office/pack.py work/ out.docx repackages and reverses the smart-quote entities.
4. python3 scripts/office/validate.py out.docx confirms basic structural sanity before shipping.

8. Workflows (Optional)

Create a new document from Markdown:

- [ ] Prepare input.md (YAML frontmatter optional)
- [ ] `cd scripts && npm install` if first run
- [ ] `node scripts/md2docx.js input.md output.docx`
- [ ] `python3 scripts/office/validate.py output.docx`
- [ ] Open in Word/LibreOffice for a spot-check

Round-trip an existing document:

- [ ] `node scripts/docx2md.js input.docx extracted.md`
- [ ] Edit `extracted.md`
- [ ] `node scripts/md2docx.js extracted.md back.docx`
- [ ] `python3 scripts/office/validate.py back.docx`

Fill a template with JSON data:

- [ ] Prepare template.docx with `{{placeholders}}`
- [ ] Prepare data.json matching the placeholder keys
- [ ] `python3 scripts/docx_fill_template.py template.docx data.json out.docx --strict`
- [ ] Confirm no unresolved placeholders on stderr

9. Best Practices & Anti-Patterns

Rationalization Table

10. Quick Reference

11. Examples (Few-Shot)

Full fixture: examples/fixture-simple.md.

Input — user request:

Convert report.md to a .docx and check it's structurally sound.

Output — agent action (abbreviated):

cd skills/docx/scripts && npm install          # one-time setup
node scripts/md2docx.js report.md report.docx
python3 scripts/office/validate.py report.docx

Report the exit codes and a one-line summary to the user ("report.docx created; validator OK").

Input — user request:

Fill invoice.docx with the data in customer.json, fail if anything is missing.

Output — agent action:

python3 scripts/docx_fill_template.py invoice.docx customer.json invoice-filled.docx --strict

On non-zero exit, surface the Unresolved placeholders: … stderr line to the user.

12. Resources

• references/ooxml-basics.md — .docx as a ZIP of XML parts, minimum viable structure, namespace table.
• references/docx-js-gotchas.md — docx-js pitfalls (A4 default, dual widths, numbering, image altText, TOC, rsids).
• references/tracked-changes.md — <w:ins> / <w:del> syntax, paragraph-delete markers, author attribution.
• references/templating.md — why adjacent-run merging matters, supported placeholder grammar, anti-patterns.
• scripts/office/validators/redlining.py — RedliningValidator: compare edited .docx against the original, report unmarked deletions/insertions/rewrites and author-attribution gaps. Driven by --compare-to flag on office/validate.py.
• scripts/office/shim/ — LD_PRELOAD / DYLD_INSERT_LIBRARIES shim that lets LibreOffice start inside seccomp-tightened sandboxes that block AF_UNIX. _soffice.py auto-detects and auto-compiles. See scripts/office/tests/test_shim.md for nsjail/Docker end-to-end validation.
• scripts/obsidian2md.js — Obsidian note → CommonMark CLI (TASK 030). Thin argv/exit-code wrapper; all rules live in _obsidian_lib.js.
• scripts/_obsidian_lib.js — the conversion core, required in-process by both obsidian2md.js and md2docx.js --obsidian. Knows nothing about OOXML, so the rules are testable as text-in/text-out and stay reusable by peer skills.
• examples/fixture-obsidian-vault/ — committed mini-vault driving scripts/tests/test_obsidian2md.py: app.json, embeds with size hints, a %-in-name attachment, a space-named directory, and a mutual-transclusion pair.
• scripts/_math_lib.js — $…$/$$…$$ extraction, sentinel substitution, and KaTeX → MathML → mathml2omml OMML batch rendering (TASK 031). Required in-process by md2docx.js; knows nothing about docx-js or OOXML beyond the OMML string it returns.
• examples/fixture-math.md — committed fixture driving scripts/tests/test_md2docx_math.py: inline math, a standalone display formula, a Pandoc-style numbered equation table, math inside **bold**, currency/escaped-dollar negative cases, a formula inside a fenced code block, and one intentionally-malformed formula.
• scripts/docx_replace.py — surgical anchor-and-action editor: --replace/--insert-after/--delete-paragraph without lossy round-trip. Requires docx_anchor.py and _actions.py siblings. Honest scope documented in --help (single-run anchor for --replace; no cross-run anchor spanning format boundaries).
• scripts/docx_anchor.py — anchor utilities: _find_paragraphs_containing_anchor, _merge_adjacent_runs, _replace_in_run. Shared by docx_replace.py and docx_add_comment.py.
• scripts/_actions.py — F2 part-walker (_iter_searchable_parts), F4 _do_replace, F5 _do_insert_after, F6 _do_delete_paragraph; extracted from docx_replace.py at task 006-07a per Q-A1 LOC guardrail.
• scripts/_app_errors.py — domain exception hierarchy for docx_replace.py (AnchorNotFound, LastParagraphCannotBeDeleted, Md2DocxFailed, Md2DocxNotAvailable, Md2DocxOutputInvalid, EmptyInsertSource).
• scripts/md2docx.js — Markdown → .docx converter (original script, preserved).
• scripts/docx2md.js — .docx → Markdown converter (original script, preserved).
• scripts/docx_fill_template.py — template placeholder filler with run canonicalisation.
• scripts/docx_accept_changes.py — LibreOffice-based tracked-change acceptor.
• scripts/preview.py — universal INPUT → PNG-grid renderer for .docx/.docm/.xlsx/.pptx/.pdf. Byte-identical across all four office skills.
• scripts/office_passwd.py — set / remove / detect password protection on .docx/.xlsx/.pptx via msoffcrypto-tool (MS-OFB Agile, Office 2010+). Byte-identical across the three OOXML skills (not pdf — pdf has its own AcroForm encryption). Pass - as the password to read it from stdin (avoids leaking via ps/shell history).
• scripts/_errors.py — --json-errors envelope helper used by every Python CLI. Schema-versioned (v=1); routes argparse usage errors through the same envelope as domain errors.
• scripts/_soffice.py — LibreOffice subprocess wrapper with sandbox-aware AF_UNIX shim auto-load.
• scripts/office/ — OOXML unpack/pack/validate utilities; byte-identically replicated to xlsx and pptx skills (docx is master — see CLAUDE.md §2 for the protocol).
• scripts/office/_encryption.py — CFB-magic detection: rejects password-protected and legacy .doc/.xls/.ppt files with exit 3 + remediation hint.
• scripts/office/_macros.py — XML-aware macro detection (Default/Override ContentType in [Content_Types].xml); writer scripts warn when output extension drops the macros.
• scripts/office/schemas/README.md — how to fetch ECMA-376 / Microsoft / W3C XSDs for strict validation.