DOCX (Anthropic, official)

tl;dr: one of the four document skills Anthropic ships under anthropics/skills (with pdf, pptx, xlsx) — SKILL.md is the routing layer, the heavy lifting is docx (npm) for creation and a Python unzip → edit word/document.xml → rezip pipeline for editing. Comments and tracked changes have dedicated helper scripts.

What it actually does

Per the frontmatter, the skill activates for any .docx / .dotx mention: create, read, edit, manipulate, find-and-replace, insert/replace images, work with tracked changes or comments, or convert content into a polished Word file. It explicitly does not cover PDFs (→ pdf skill), spreadsheets (→ xlsx), Google Docs, or general coding tasks.

Task routing (from SKILL.md)

docx-js gotchas (from SKILL.md)

docx is preinstalled — do not run npm install first. Write the script and require('docx') directly. Only install if that require fails:

• Page size defaults to A4. For US Letter set page: { size: { width: 12240, height: 15840 } } (DXA; 1440 = 1″).
• Landscape = portrait dimensions + orientation: PageOrientation.LANDSCAPE — docx-js swaps internally.
• Tables need dual widths: columnWidths on the table AND width on every cell, both WidthType.DXA (PERCENTAGE breaks in Google Docs). Columns sum to table width.
• Table shading: ShadingType.CLEAR, never SOLID (renders black).
• Lists: numbering config with LevelFormat.BULLET — never literal •.
• ImageRun requires type: ("png", "jpg", …).
• PageBreak must be inside a Paragraph.
• Never \n — use separate Paragraph elements.
• TOC: built-in HeadingLevel.*; custom heading styles need outlineLevel or they won’t appear.
• No tables as horizontal rules — use a paragraph bottom border.
• Dot-leader + right-aligned on same line: PositionalTab (alignment: PositionalTabAlignment.RIGHT, leader: PositionalTabLeader.DOT), not literal . or space padding.

Editing an existing docx — the pipeline

unzip -q doc.docx -d unpacked/
find unpacked -type l -delete   # strip symlink entries — external docx is untrusted
python scripts/merge_runs.py unpacked/   # coalesce fragmented runs so text is findable
# edit unpacked/word/document.xml in place — do NOT reformat or pretty-print
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx   # XSD checks; --auto-repair fixes common issues
# redlining? add --author "<the name you redlined under>" to check every edit is tracked

The SKILL.md calls out specifically: Word splits text across many <w:r> runs (revision ids, spell-check markers) so a phrase you can see in the document often doesn’t exist as a contiguous string in the XML. merge_runs.py merges adjacent identically-formatted runs without changing content or rendering.

Gotchas

• scripts/office/soffice.py is the headless renderer. LibreOffice + Poppler are system deps; without them the render-and-read step fails silently. Script paths are relative to the skill’s directory.
• merge_runs.py then edit, not the other way around. Editing fragmented XML often turns into “find the text” → “the string isn’t there as one piece” loops. The merge step makes text findable without changing the render.
• Tracked-changes hygiene: inside <w:del>, the text element is <w:delText>, not <w:t>. A deleted paragraph mark (<w:pPr><w:rPr><w:del .../></w:rPr></w:pPr>) means “merge this paragraph into the next” — so deleting a paragraph outright is that plus a <w:del> around every run. The <w:del/> must come before the rPr’s other children; their order is schema-enforced.
• --author "<name>" on validate.py is the redlining check. Without it, you won’t catch text you changed without a <w:ins>/<w:del> around it — invisible in the accepted view.
• Accepting deleted paragraph marks has two paths: accept_changes.py (LibreOffice) joins paragraphs correctly except when followed by an empty spacer; pandoc --track-changes=accept never joins. An empty bullet in either view is an artifact of that view, not a defect.
• Comments need six cross-linked files. Use scripts/comment.py — it writes comments.xml, commentsExtended.xml, commentsIds.xml, commentsExtensible.xml, the relationships, and the content-type overrides. After running, you still have to place the <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> markers into word/document.xml; until then the comment exists but isn’t anchored to anything visible.
• License is Proprietary. LICENSE.txt restricts redistribution and derivative works. You use the skill; you don’t fork it.
• Install command is /plugin install, not npx skills add. The README does not document an npx workflow. Anyone running npx skills add anthropics/skills is using a third-party installer, not Anthropic’s path.
• sandbox_test untested. We read SKILL.md and the marketplace manifest, not exercised the docx pipeline in a sandbox.

Install

The skill is one entry in the document-skills plugin of anthropic-agent-skills (per .claude-plugin/marketplace.json on 2026-09-10 — a 1.7 KB marketplace manifest listing five plugins: document-skills, example-skills, claude-api, academy-guide, discernment-nudge). Install requires the marketplace to be registered first.

# Claude Code — one-time marketplace registration
/plugin marketplace add anthropics/skills

# Install the document-skills plugin (includes docx, pdf, pptx, xlsx)
/plugin install document-skills@anthropic-agent-skills

On Claude.ai, the document skills are pre-built for paid plans. On the API, attach via the container.skills parameter:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "container": {
    "skills": [
      { "type": "anthropic", "skill_id": "docx", "version": "latest" }
    ]
  },
  "messages": [
    { "role": "user", "content": "Draft a Word memo at /mnt/memo.docx summarizing the Q3 incident review" }
  ],
  "tools": [
    { "type": "code_execution_20250825", "name": "code_execution" }
  ]
}

Skills require code_execution_20250825; pinned to the Claude API ID claude-opus-5 in the example. Use the Files API to pull the result back when Claude writes a new .docx.

Related

• Anthropic PDF (official skill) — sibling in the document-skills plugin, same Python-tooling pattern
• Anthropic Doc Co-Authoring (official skill) — pair it with docx when the work is structured writing that ends as a Word file
• Anthropic Academy Guide — same anthropics/skills repo, but a routing skill over a live catalog
• Claude skills guide — what the cache.directory skills shelf actually is