ada-docx-merge

Merge Word .docx chapters across documents with template-based format fidelity via XML surgery.

Updated Jul 23, 2026
One-click install
npx skills add https://github.com/wubing7755/Ada --skill ada-docx-merge-wubing7755
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ada-docx-merge
Source: https://github.com/wubing7755/Ada/tree/main/skills/software-development/ada-docx-merge
Command: npx skills add https://github.com/wubing7755/Ada --skill ada-docx-merge-wubing7755

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires lxml, python-docx, and includes references (resource) components.

What problem does it solve? Merging chapters from multiple Word .docx files while preserving a designated template's formatting is error-prone: styleIds differ across same-source documents, VML images break, tracked changes leak into deliverables, section breaks get destroyed, and SEQ field numbering goes out of sequence. This Skill performs element-level surgery on word/document.xml using the format template as the ZIP base, so styles, numbering, headers, and section structure remain intact. ## Core Features & Use Cases - Chapter-level cross-document merge: Copy the template docx as base, slice body child elements by heading text and pStyle, deep-copy source blocks in, and remap pStyle/rStyle/tblStyle by style name rather than styleId. - Post-processing pipeline: Accept tracked changes (w:ins/w:del), remove dangling comment references, unify page size to A4 while preserving landscape sections, normalize captions, and renumber SEQ fields with a state machine that handles split instrText runs. - Specialized operations: Single-artifact extraction (large table plus caption into a template copy), supplementary image merging by media MD5 diff, in-place image replacement by overwriting media bytes only, cross-document table replacement, and SD design-number resequencing with traceability-matrix synchronization. - Use Case: A client template plus two content-source reports must be combined so chapters 1-4 come from document A, chapter 5.2 from document B, all formatted to the template, with tracked changes accepted and figure/table numbers resequenced before delivery. ## Quick Start Merge chapters 1 through 4 from the source report into the client template docx, keeping the template's formatting, accepting all tracked changes, and renumbering the figure and table captions.

Frequently Asked Questions about ada-docx-merge

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I merge chapters from multiple Word documents while keeping one template's formatting?

Copy the format-authority docx as the ZIP base and edit only word/document.xml: delete the chapters to replace, deep-copy body elements from source documents, and insert them at the target position. The base styles.xml, numbering.xml, and section structure stay untouched, so template formatting holds automatically.

Why do styles break when merging docx files from the same project?

Same-source documents often assign different styleIds to the same style name, so copied content referencing source styleIds renders with wrong styles in the base. Build a styleId-to-name-to-base-styleId mapping and rewrite every pStyle, rStyle, and tblStyle reference by name.

How do I fix figure and table numbering after merging Word documents?

Renumber SEQ field cached results with a state machine over fldChar begin/end runs, detecting the field label by the tag character since instrText is often split across runs. Rewrite the result w:t values in document order and verify the sequence is continuous.

Why does a merged docx show gray revision balloons in Word?

The source document contained tracked changes (w:ins/w:del) that were carried into the merged output. Accept revisions before delivery by unwrapping w:ins elements, deleting w:del elements, and removing dangling comment references whose comment parts were not copied.

Can I replace images in a docx without changing layout or captions?

Yes, use in-place replacement: rewrite only the media file bytes inside the ZIP while leaving document.xml untouched, preserving VML shape sizes, rIds, and captions. First verify the target rId and media file are each referenced exactly once to avoid affecting other chapters.

What are the limitations of python-docx for cross-document merging?

python-docx paragraphs include table-cell paragraphs, so its indexes diverge from lxml body child-element indexes and mislead anchor or context lookups. Use lxml direct-child views for boundary slicing, and note python-docx cannot handle VML images, section breaks, or field renumbering alone.