DOCX Editing

DOCX Editing Skill

Tool Selection

Author name for tracked changes: Use the user's name from anylegal.md (the "About Me" section). If unknown, use "Anylegal.ai".

edit_document is the default tool for editing existing DOCX files. Pass plain-text old_text / new_text; the server generates <w:ins> / <w:del> markup and preserves run properties.

Rules:

• ONE CHANGE = ONE edit_document CALL. Multiple changes → multiple calls.
• Never use run_code for ordinary text edits — even placeholder fills like [●] are edit_document cases.
• For STRUCTURAL edits the plain-text tools can't express (delete clause + paragraph mark, insert multi-paragraph content, edit styles.xml / headers / footers), invoke Skill('docx-xml') for the run_code + lxml + zipfile reference.
• For creating a NEW DOCX from scratch, invoke Skill('draft') instead — that skill uses docx-js for new-doc creation.

Workflows

Basic text replacement

read_document(path="Contract.docx")          → get current text
edit_document(path="Contract.docx",
              old_text="the laws of the State of Delaware",
              new_text="the laws of England and Wales",
              explanation="Change governing law")

Auto-clones the original to Contract_v2.docx on first edit. Response includes:

• revision_ids: list of w:id values for the tracked changes created
• matched_text: the text that was actually matched
• context_around_edit: surrounding text

Range deletion (delete entire sections)

edit_document(path="Contract_v2.docx",
              start_text="8. NON-COMPETE", end_text="9. GOVERNING LAW",
              explanation="Remove non-compete clause")

Disambiguating duplicate text

edit_document(path="Contract_v2.docx", old_text="written notice", new_text="prior written notice",
              near_text="termination",
              explanation="Disambiguate to the termination notice clause only")

Reverting a specific change

revert_edit(path="Contract_v2.docx", revision_ids=[1001, 1002])

Checking what's been changed

get_revision_stats(path="Contract_v2.docx")

Returns insertion/deletion counts, authors, revision IDs.

Accept / reject finalization

Two distinct shapes, distinct semantics:

Both routed through LibreOffice — handles every OOXML edge case (nested changes, paragraph marks, table cells, content controls, comment anchors). Returns {success, path, remaining_insertions, remaining_deletions, round_finalized?} — both counts should be 0 on success. When round_finalized: true appears in the response, surface this to the user (e.g. "Round 1 finalized — next edit will start v3"). The selective accept_changes / reject_changes tools are intra-round micro-edits and do not trigger the round-bump.

Template fill (clean output, no tracked changes)

instantiate_template(
  template_path="Templates/Board_Resolution.docx",
  output_path="Acme Board Resolution 2026-04-25.docx",
  replacements={
    "[Company Name]": "Acme Corporation",
    "[Date]": "25 April 2026",
    "[Resolution Number]": "2026-001",
  },
)

The template is untouched. The output is a clean final document with the template's formatting preserved (run properties, paragraph styles, headers, footers all intact).

Disambiguating repeated placeholders. If the same token appears multiple times in the template (e.g. a generic [●] or [___] marker showing up at many fill points), each replacement key must be a unique-in-document string — include surrounding context so the matcher targets the right span. Pattern:

replacements={
  "Term of [●] months":      "Term of 24 months",
  "Cap of $[●]":              "Cap of $5,000,000",
  "Discount of [●] percent":  "Discount of 20 percent",
}

The longer key is unambiguous; identical short keys like [●] would only fill the first occurrence (or fail with ambiguity). For reviewable per-placeholder fills (rare — when each fill needs separate sign-off), use clone_document + edit_document per placeholder instead, then finalize with accept_all_changes.

Selective accept / reject (per-change)

get_revision_stats(path="Contract_v2.docx", with_snippets=True)
  → {revisions: [{id: 1003, type: "insertion", author: "Counterparty",
                  text_snippet: "...sole and absolute discretion...",
                  context_around: "...the Buyer in its sole and absolute..."},
                 ...]}

accept_changes(path="Contract_v2.docx", revision_ids=[1003, 1005])
reject_changes(path="Contract_v2.docx", revision_ids=[1004])

Use accept_changes / reject_changes when the lawyer wants per-revision control ("accept the indemnity edits, leave the IP edits open"). Use the _all_changes variants for batch finalization. Both auto-clone the original to _v2.docx on first call so the pristine source isn't mutated.

Verification

Every edit operation must include verification. Check success: true and inspect context_around_edit from the response. If the matched span looks wrong, call read_document(path=...) to confirm the current state before continuing.

Anti-patterns

Don't reach for run_code + python-docx for placeholder fills on existing DOCX. Use edit_document, one call per placeholder. python-docx's run-level .text.replace() subtly corrupts complex legal templates: it strips non-target glyphs (other placeholders, special characters), collapses <w:rPr> run properties across runs (loses bold/font/size), and has no reliable API for footnotes, bookmarks, TableOfContents, or internal hyperlinks.

Don't create a new DOCX in this skill. Creation belongs in the draft skill — invoke Skill('draft').

Don't write lxml-based accept/reject recipes in run_code. The accept_all_changes / reject_all_changes tools route through LibreOffice and handle every OOXML edge case correctly. Hand-rolled lxml accept/reject misses paragraph-mark + content-control edge cases and produces "unreadable content" dialogs in Word.