docx

---
name: docx
description: Use when creating, reading, or editing Word .docx files — reports, memos, letters, templates with TOCs, tables, images, tracked changes, or comments — via docx-js or raw XML round-trips.
source: https://github.com/anthropics/skills/tree/main/skills/docx
generated: 2026-07-02T18:41:40.621Z
category: tool
audience: general
---

## When to use

- Producing a polished Word document with headings, a table of contents, tables, or page numbers
- Editing an existing .docx by unpacking its XML, changing it, and repacking
- Adding tracked changes or comments to a Word file, or accepting existing ones
- Extracting or reorganizing content from a .docx, or converting a legacy .doc first

## Key concepts

### .docx is a ZIP of XML

A Word file is a ZIP archive of XML parts. Reading uses pandoc or a raw unpack; creating uses docx-js; editing means unpack → edit XML → repack via the skill's scripts.

### Create with docx-js

New documents are generated in JavaScript with the docx library (Document, Paragraph, TextRun, Table, etc.), then written with Packer.toBuffer. Install globally with npm install -g docx and validate afterward.

### Edit via unpack → edit → pack

unpack.py extracts and pretty-prints XML (merging runs, converting smart quotes to entities); you edit word/*.xml with the Edit tool directly; pack.py validates, condenses, and rebuilds the .docx.

### DXA units and explicit page size

Measurements are in DXA where 1440 DXA = 1 inch. docx-js defaults to A4, so US Letter (12240 x 15840) must be set explicitly; content width for 1-inch margins is 9360.

### Tracked changes and comments in XML

Insertions use <w:ins>, deletions use <w:del> with <w:delText>; author defaults to 'Claude'. comment.py handles comment boilerplate, and commentRange markers are siblings of <w:r>, never inside a run.

## API reference

```
npx skills add anthropics/skills --skill docx
```

Install the Word document (.docx) creation and editing skill.

```
npx skills add anthropics/skills --skill docx
```

```
python scripts/office/unpack.py document.docx unpacked/ ; python scripts/office/pack.py unpacked/ output.docx --original document.docx
```

Unpack a .docx to editable XML, then repack it with validation and auto-repair.

```
python scripts/office/unpack.py document.docx unpacked/
# edit files in unpacked/word/
python scripts/office/pack.py unpacked/ output.docx --original document.docx
```

```
python scripts/office/validate.py doc.docx
```

Validate a generated .docx; on failure, unpack, fix the XML, and repack.

```
python scripts/office/validate.py doc.docx
```

## Gotchas

- docx-js defaults to A4 — set US Letter (12240 x 15840 DXA) explicitly for US documents
- Never use unicode bullets; use LevelFormat.BULLET with a numbering config instead
- Tables need dual widths — set columnWidths on the table AND width on each cell, and they must match and sum correctly
- Always use WidthType.DXA for table widths; WidthType.PERCENTAGE breaks in Google Docs
- Use ShadingType.CLEAR (not SOLID) for table shading or you get black backgrounds
- Never use '\n' — use separate Paragraph elements; PageBreak must live inside a Paragraph
- ImageRun requires the 'type' parameter (png/jpg/etc.); TOC headings must use HeadingLevel only with outlineLevel set
- Legacy .doc files must be converted to .docx (via soffice.py) before editing

---
Generated by SkillMake from https://github.com/anthropics/skills/tree/main/skills/docx on 2026-07-02T18:41:40.621Z.
Verify against source before relying on details.

File: ~/.claude/skills/docx/SKILL.md