anthropics/skills · skills/docx/SKILL.md
docx
“Anthropic's Word skill: a tight list of docx pitfalls, plus real scripts for redlines and comments”
What it does
Creates, reads and edits .docx files. New documents are built with the docx npm library, guided by a list of known pitfalls. Existing ones are edited as raw XML. Helper scripts handle run merging, validation, tracked changes, comments and rendering pages for a visual check.
- When the agent uses it
- When a user wants to create, read or edit a Word .docx/.dotx file, such as a report, memo or letter, or work with tracked changes, comments or find-and-replace.
- Who it is for
- For anyone whose agent produces or redlines Word files. Skip it if you only work with PDFs, spreadsheets or Google Docs.
- What it costs
- 64 lines, about 1.9k tokens once the agent loads it, plus 5 files beside it.
Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.
What it tells the agent to do
- Pick the approach: docx-js script to create, unzip and edit XML to change, pandoc to read
- When creating, write a docx (npm) script and apply the listed pitfalls (page size, table widths, lists, TOC)
- Render the result to PDF, then to JPEGs, and look at the pages
- When editing, unzip, delete symlinks, merge runs, edit document.xml in place, then rezip
- Validate against the original, adding --author to confirm every redline edit is tracked
- Add comments with comment.py, then place the printed anchor markers in document.xml
- Produce a clean copy with accept_changes.py, and check paragraph deletions in the XML
Lines worth reading
Straight from the file, with why each one matters.
line 21The model knows the API; these are the footguns:
The right way to use context: skip the tutorial and list only the traps.
line 26use `ShadingType.CLEAR`, never `SOLID` (renders black)
The kind of rule you only learn by shipping a black table to a client.
line 53strip symlink entries — docx from external parties is untrusted
A quiet security step: a malicious zip can't use symlinks to reach outside the work folder.
line 72An empty bullet in either view is an artifact of that view, not a defect in the document.
Stops the agent from 'fixing' a bug that only exists in the preview tool.
line 87until you place those markers, the comment exists but is not visible
Explains the classic way a comment silently goes missing in Word.
Watch out for
- Low
It calls scripts/office/soffice.py and validate.py, which are not among the files listed in this folder. The verify and validate steps may fail if they are missing.
line 57python scripts/office/validate.py out.docx --original doc.docx
- Low
It falls back to installing an npm package from the registry if docx is not already present.
line 21Only if that require fails: `npm install docx`.
- Low
The rezip command deletes any existing out.docx in the parent folder without asking.
line 56rm -f ../out.docx
The scorecard
- TriggerSays when to use it9/10
Says what and when, with the words a request would use, and lists what not to use it for.
- FocusOne clear job8/10
Covers everything Word, but it is all one file type with one consistent toolchain.
- LeanLight to load9/10
About 90 dense lines with no narration. The heavy lifting lives in scripts.
- ConcreteSteps you can follow9/10
Exact commands, pitfall fixes and a visual check. It lacks a creation example.
- SafeSafe to run9/10
Local tools only. It strips symlinks from untrusted files. Nothing hijacks the agent.
What it does well
- Lists only the docx-js pitfalls, like dual table widths and A4 defaults, instead of reteaching the API
- Makes the agent render pages to images and look at them, a real way to confirm the result
- Explains why text search fails in Word XML and ships merge_runs.py to fix it
How it could be better
Ship or point to the scripts/office helpers
soffice.py and validate.py are called but are not in this folder's file list, so verify and validate can break.
Add> `soffice.py` and `validate.py` live in `<path to shared office scripts>`; copy that folder to `scripts/office/` before running the commands below.
Add a minimal docx-js skeleton
A working starting script with US Letter and a heading would prevent the pitfalls instead of just listing them.
Add```js const fs = require('fs'); const { Document, Packer, Paragraph, HeadingLevel } = require('docx'); const doc = new Document({ sections: [{ properties: { page: { size: { width: 12240, height: 15840 } } }, children: [ new Paragraph({ text: '<title>', heading: HeadingLevel.HEADING_1 }) ] }] }); Packer.toBuffer(doc).then(b => fs.writeFileSync('<output>.docx', b)); ```State what done looks like for edits
The skill checks output well, but it never says which result counts as finished.
AddDone when: `validate.py` reports no errors (no untracked edits when redlining), and every rendered page has been viewed with no layout breaks.
In the skill’s folder
Listed, not read: the agent opens these only when SKILL.md sends it there.
LICENSE.txtscripts/__init__.pyscripts/accept_changes.pyscripts/comment.pyscripts/merge_runs.py
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.