Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', 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 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.
Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', 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 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.
license
Proprietary. LICENSE.txt has complete terms
DOCX creation, editing, and analysis
Overview
A .docx file is a ZIP archive containing XML files.
Quick Reference
Task
Approach
Read/analyze content
pandoc or unpack for raw XML
Create new document
Use docx-js - see Creating New Documents below
Edit existing document
Unpack → edit XML → repack - see Editing Existing Documents below
Converting .doc to .docx
Legacy .doc files must be converted before editing:
After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.
python scripts/office/validate.py doc.docx
Page Size
// CRITICAL: docx-js defaults to A4, not US Letter// Always set page size explicitly for consistent resultssections: [{
properties: {
page: {
size: {
width: 12240, // 8.5 inches in DXAheight: 15840// 11 inches in DXA
},
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins
}
},
children: [/* content */]
}]
Common page sizes (DXA units, 1440 DXA = 1 inch):
Paper
Width
Height
Content Width (1" margins)
US Letter
12,240
15,840
9,360
A4 (default)
11,906
16,838
9,026
Landscape orientation: docx-js swaps width/height internally, so pass portrait dimensions and let it handle the swap:
size: {
width: 12240, // Pass SHORT edge as widthheight: 15840, // Pass LONG edge as heightorientation: PageOrientation.LANDSCAPE// docx-js swaps them in the XML
},
// Content width = 15840 - left margin - right margin (uses the long edge)
Styles (Override Built-in Headings)
Use Arial as the default font (universally supported). Keep titles black for readability.
CRITICAL: Tables need dual widths - set both columnWidths on the table AND width on each cell. Without both, tables render incorrectly on some platforms.
// CRITICAL: Always set table width for consistent rendering// CRITICAL: Use ShadingType.CLEAR (not SOLID) to prevent black backgroundsconst border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };
newTable({
width: { size: 9360, type: WidthType.DXA }, // Always use DXA (percentages break in Google Docs)columnWidths: [4680, 4680], // Must sum to table width (DXA: 1440 = 1 inch)rows: [
newTableRow({
children: [
newTableCell({
borders,
width: { size: 4680, type: WidthType.DXA }, // Also set on each cellshading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR not SOLIDmargins: { top: 80, bottom: 80, left: 120, right: 120 }, // Cell padding (internal, not added to width)children: [newParagraph({ children: [newTextRun("Cell")] })]
})
]
})
]
})
Table width calculation:
Always use WidthType.DXA — WidthType.PERCENTAGE breaks in Google Docs.
// Table width = sum of columnWidths = content width// US Letter with 1" margins: 12240 - 2880 = 9360 DXAwidth: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360] // Must sum to table width
Width rules:
Always use WidthType.DXA — never WidthType.PERCENTAGE (incompatible with Google Docs)
Table width must equal the sum of columnWidths
Cell width must match corresponding columnWidth
Cell margins are internal padding - they reduce content area, not add to cell width
For full-width tables: use content width (page width minus left and right margins)
// CRITICAL: PageBreak must be inside a ParagraphnewParagraph({ children: [newPageBreak()] })
// Or use pageBreakBeforenewParagraph({ pageBreakBefore: true, children: [newTextRun("New page")] })
// Right-align text on same line (e.g., date opposite a title)newParagraph({
children: [
newTextRun("Company Name"),
newTextRun("\tJanuary 2025"),
],
tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})
// Dot leader (e.g., TOC-style)newParagraph({
children: [
newTextRun("Introduction"),
newTextRun({ children: [
newPositionalTab({
alignment: PositionalTabAlignment.RIGHT,
relativeTo: PositionalTabRelativeTo.MARGIN,
leader: PositionalTabLeader.DOT,
}),
"3",
]}),
],
})
Multi-Column Layouts
// Equal-width columnssections: [{
properties: {
column: {
count: 2, // number of columnsspace: 720, // gap between columns in DXA (720 = 0.5 inch)equalWidth: true,
separate: true, // vertical line between columns
},
},
children: [/* content flows naturally across columns */]
}]
// Custom-width columns (equalWidth must be false)sections: [{
properties: {
column: {
equalWidth: false,
children: [
newColumn({ width: 5400, space: 720 }),
newColumn({ width: 3240 }),
],
},
},
children: [/* content */]
}]
Force a column break with a new section using type: SectionType.NEXT_COLUMN.
Table of Contents
// CRITICAL: Headings must use HeadingLevel ONLY - no custom stylesnewTableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" })
Set page size explicitly - docx-js defaults to A4; use US Letter (12240 x 15840 DXA) for US documents
Landscape: pass portrait dimensions - docx-js swaps width/height internally; pass short edge as width, long edge as height, and set orientation: PageOrientation.LANDSCAPE
Never use \n - use separate Paragraph elements
Never use unicode bullets - use LevelFormat.BULLET with numbering config
PageBreak must be in Paragraph - standalone creates invalid XML
ImageRun requires type - always specify png/jpg/etc
Always set table width with DXA - never use WidthType.PERCENTAGE (breaks in Google Docs)
Tables need dual widths - columnWidths array AND cell width, both must match
Table width = sum of columnWidths - for DXA, ensure they add up exactly
Always add cell margins - use margins: { top: 80, bottom: 80, left: 120, right: 120 } for readable padding
Use ShadingType.CLEAR - never SOLID for table shading
Never use tables as dividers/rules - cells have minimum height and render as empty boxes (including in headers/footers); use border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } } on a Paragraph instead. For two-column footers, use tab stops (see Tab Stops section), not tables
TOC requires HeadingLevel only - no custom styles on heading paragraphs
Override built-in styles - use exact IDs: "Heading1", "Heading2", etc.
Include outlineLevel - required for TOC (0 for H1, 1 for H2, etc.)
Extracts XML, pretty-prints, merges adjacent runs, and converts smart quotes to XML entities (“ etc.) so they survive editing. Use --merge-runs false to skip run merging.
Step 2: Edit XML
Edit files in unpacked/word/. See XML Reference below for patterns.
Use "Claude" as the author for tracked changes and comments, unless the user explicitly requests use of a different name.
Use the Edit tool directly for string replacement. Do not write Python scripts. Scripts introduce unnecessary complexity. The Edit tool shows exactly what is being replaced.
CRITICAL: Use smart quotes for new content. When adding text with apostrophes or quotes, use XML entities to produce smart quotes:
<!-- Use these entities for professional typography --><w:t>Here’s a quote: “Hello”</w:t>
Entity
Character
‘
‘ (left single)
’
’ (right single / apostrophe)
“
“ (left double)
”
” (right double)
Adding comments: Use comment.py to handle boilerplate across multiple XML files (text must be pre-escaped XML):
python scripts/comment.py unpacked/ 0 "Comment text with & and ’"
python scripts/comment.py unpacked/ 1 "Reply text" --parent 0 # reply to comment 0
python scripts/comment.py unpacked/ 0 "Text" --author "Custom Author"# custom author name
Then add markers to document.xml (see Comments in XML Reference).
Validates with auto-repair, condenses XML, and creates DOCX. Use --validate false to skip.
Auto-repair will fix:
durableId >= 0x7FFFFFFF (regenerates valid ID)
Missing xml:space="preserve" on <w:t> with whitespace
Auto-repair won't fix:
Malformed XML, invalid element nesting, missing relationships, schema violations
Common Pitfalls
Replace entire <w:r> elements: When adding tracked changes, replace the whole <w:r>...</w:r> block with <w:del>...<w:ins>... as siblings. Don't inject tracked change tags inside a run.
Preserve <w:rPr> formatting: Copy the original run's <w:rPr> block into your tracked change runs to maintain bold, font size, etc.
XML Reference
Schema Compliance
Element order in <w:pPr>: <w:pStyle>, <w:numPr>, <w:spacing>, <w:ind>, <w:jc>, <w:rPr> last
Whitespace: Add xml:space="preserve" to <w:t> with leading/trailing spaces
Inside <w:del>: Use <w:delText> instead of <w:t>, and <w:delInstrText> instead of <w:instrText>.
Minimal edits - only mark what changes:
<!-- Change "30 days" to "60 days" --><w:r><w:t>The term is </w:t></w:r><w:delw:id="1"w:author="Claude"w:date="..."><w:r><w:delText>30</w:delText></w:r></w:del><w:insw:id="2"w:author="Claude"w:date="..."><w:r><w:t>60</w:t></w:r></w:ins><w:r><w:t> days.</w:t></w:r>
Deleting entire paragraphs/list items - when removing ALL content from a paragraph, also mark the paragraph mark as deleted so it merges with the next paragraph. Add <w:del/> inside <w:pPr><w:rPr>:
<w:p><w:pPr><w:numPr>...</w:numPr><!-- list numbering if present --><w:rPr><w:delw:id="1"w:author="Claude"w:date="2025-01-01T00:00:00Z"/></w:rPr></w:pPr><w:delw:id="2"w:author="Claude"w:date="2025-01-01T00:00:00Z"><w:r><w:delText>Entire paragraph content being deleted...</w:delText></w:r></w:del></w:p>
Without the <w:del/> in <w:pPr><w:rPr>, accepting changes leaves an empty paragraph/list item.
Rejecting another author's insertion - nest deletion inside their insertion:
After running comment.py (see Step 2), add markers to document.xml. For replies, use --parent flag and nest markers inside the parent's.
CRITICAL: <w:commentRangeStart> and <w:commentRangeEnd> are siblings of <w:r>, never inside <w:r>.
<!-- Comment markers are direct children of w:p, never inside w:r --><w:commentRangeStartw:id="0"/><w:delw:id="1"w:author="Claude"w:date="2025-01-01T00:00:00Z"><w:r><w:delText>deleted</w:delText></w:r></w:del><w:r><w:t> more text</w:t></w:r><w:commentRangeEndw:id="0"/><w:r><w:rPr><w:rStylew:val="CommentReference"/></w:rPr><w:commentReferencew:id="0"/></w:r><!-- Comment 0 with reply 1 nested inside --><w:commentRangeStartw:id="0"/><w:commentRangeStartw:id="1"/><w:r><w:t>text</w:t></w:r><w:commentRangeEndw:id="1"/><w:commentRangeEndw:id="0"/><w:r><w:rPr><w:rStylew:val="CommentReference"/></w:rPr><w:commentReferencew:id="0"/></w:r><w:r><w:rPr><w:rStylew:val="CommentReference"/></w:rPr><w:commentReferencew:id="1"/></w:r>
