DOCX
Create Word documents or edit existing files with attention to structure, tracked changes, and page layout.
npx skills add anthropics/skills --skill docx What it does
A Word document contains styles, package relationships, comments, and layout rules beyond plain text. The DOCX skill separates new-document creation from existing-document editing and asks the agent to inspect rendered pages.
What changes after install
- Uses docx-js for new files and package editing for existing Word documents.
- Covers document headings, tables, numbering, comments, and tracked changes.
- Includes structural checks and rendered-page inspection.
Install
Run this command with Node.js 22.20 or later and select your agent in the Skills CLI.
npx skills add anthropics/skills --skill docx Before using DOCX
- New-document generation uses Node.js and the docx npm package. Reading and rendering workflows use Pandoc, LibreOffice and Poppler; the bundled document helpers require Python.
Read the reviewed setup instructions for the selected workflow.
When to use it
- Creating a Word report with headings, tables, and consistent formatting.
- Editing an existing DOCX or DOTX while retaining its document conventions.
When not to use it
- Using a Word-generation library as if it could safely open and modify every existing document.
- Extracting rows from a scanned PDF when no editable Word source is available.
- Maintaining formulas in a budget that readers need to recalculate after changing quantities.
A worked example
Give the agent terms.docx and ask: “In the Payment terms row, change 30 days to 45 days. Track the edit under Morgan Lee. Keep the separate 30-day cancellation period and all reviewer comments. Return terms-review.docx.” Both clauses contain the same number. Someone opening the file must be able to accept the payment change and still see who commented on the original wording.
- Keep the original for comparison. Open the table and identify the row by its Payment terms label and the wording in the adjacent cell. Note which passage each existing comment highlights. Include the cancellation clause in your comparison even though the request leaves it alone. A search for “30 days” finds candidate passages but cannot tell you which obligation to change.
- Unpack a working copy and locate the table row in
word/document.xml. Read the text runs in order across the target cell. If Word put “30” and “ days” in different runs, the edit only needs to touch the number. Keep the formatting of the surrounding text and the comment markers in place. Avoid reformatting the whole XML file when saving this small edit. - Record 30 as a tracked deletion and 45 as a tracked insertion under Morgan Lee. The upstream guide shows where the revision ID, author and date belong and uses
w:delTextfor deleted text. Leave the space and “days” outside the revision if they are unchanged. This gives a reviewer one number to accept or reject without marking the entire cell as replaced. - Repack the working copy as
terms-review.docx. From the skill directory, with both files there, runpython scripts/office/validate.py terms-review.docx --original terms.docx --author "Morgan Lee". With both options, the validator flags text changed anywhere without a tracked insertion or deletion. In Word, select the revised number and look for Morgan Lee’s name on the revision. - Open the result in Word with revisions visible. In the Payment terms row, the reviewer should see 30 deleted and 45 inserted under Morgan Lee’s name. Select the cancellation clause separately. If it also shows a revision, return to the original and narrow the edit to the payment cell before handing over the review copy.
The example follows the upstream SKILL.md sections on editing and comments. The comparison options are documented in scripts/office/validate.py.
Troubleshooting
- A visible phrase cannot be found in the XML. Word may split it across text runs. Use the bundled
merge_runs.pyon the working copy to join adjacent runs with identical formatting. If the phrase crosses a style change, inspect both runs before editing. - A comment has text but no margin marker. The comment helper prints markers to place in the document. For a new comment, put the range around the intended words and insert the matching reference. For an existing one that disappeared, compare its markers with the original before creating another comment. Reopen the copy and click the passage.
- A heading is missing from the table of contents. Inspect its paragraph style. Apply the appropriate built-in heading level or set the outline level on its custom style. Check that the entry leads to that heading. If the recipient will convert the document to another format, follow the entry in that copy too.
How it chooses an approach
If the user only needs to read the wording, extract it with Pandoc. For a report written from scratch, use the docx npm package and define the page size and heading styles before adding content. A request for the current cancellation period can usually end with a quotation. A request for the amended contract requires an editable file that still carries the reviewers’ work.
If reviewers need their original comments, numbering or revision history, edit the existing package. Convert a legacy .doc to .docx before unpacking it. In the payment example, rebuilding the table from extracted text would give you the words and figures, but the comment IDs and the ranges they refer to live in the original document. Start with that file even if the table would be easy to recreate.
When to use another skill
- Give PDF the signed PDF when the task is to extract clauses from that copy.
- Give XLSX the quantities and rates when the recipient needs an editable cost model.
- Give Internal Comms the approved terms and intended audience when the deliverable is a staff announcement.
What to check after it runs
- On separate copies, accept and reject the payment revision. Payment terms should read 45 and 30 days respectively. Cancellation should read 30 in both. Read the entire cell in each copy, including the space before “days.” If rejecting the change leaves “3045 days” or just “days,” compare the insertion and deletion with the original cell before sending the file.
- In the review copy, click each original comment. Compare its highlighted passage, author and text with the original. A comment that still appears in the margin but now points at the entire table deserves another look, especially when its old anchor touched the edited number.
- Inspect the rendered pages for a split table row or clipped text. Compare the page containing Payment terms and the beginning of the following page with the original. Check the unit after the number and the right edge of the cell at reading size. An XML validator cannot tell whether “days” is visible on the page.
- Reopen the file intended for delivery and display all revisions. Confirm that it retains the pending change, names Morgan Lee on the payment edit, and includes the original review comments. Keep the accepted and rejected comparison copies separate so the recipient receives the file they can still review.
FAQ sources: Word opening error · #12, missing comment · #1733, empty contents after conversion · #1002, Windows rendering tools · #2206.
Related workflows
More in Documents
- PDF — PDF extraction
- PPTX — editable slide decks
- Documentation and ADRs — architecture decision records
- JSON Canvas — editable concept maps
Related skills in other categories
FAQ
- Why can Pandoc read my edited document when Word refuses to open it?
- In issue #12, adding a comment also reformatted the underlying XML. Pandoc could still extract the text. Start from the original file, preserve the XML whitespace during the edit, and reopen the repacked document in Word before handing it back.
- Why did a reviewer’s comment disappear even though the file passed validation?
- Issue #1733 describes an edit that kept the comment text but removed its anchor. Check the original passage against the revised one. The range markers and reference must still point to the comment. Open the file in Word and select that passage to verify the reviewer’s note.
- Why is the table of contents empty after conversion to Google Docs?
- In issue #1002, Word displayed the table of contents, but Google Docs relied on cached entries that were absent. Use the documented heading levels when creating the Word file. If recipients will convert it, test that conversion and follow a heading link in the converted copy.
- How can I review page layout on Windows if the rendering tools are missing?
- Issue #2206 describes a machine without LibreOffice or Poppler. The guide’s route needs both to produce page images. If Word is available, inspect every page there and say which application you used. If nobody has inspected the pages, leave visual verification open.