{"slug":"docx-8","title":"docx","summary":"When the office_edit tool is available and the document is in the workspace, use the office skill instead: the user watches the edit live. Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx) or Word templates (.dotx). Triggers includ","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-17T09:13:09.422057Z","repo":{"url":"https://github.com/invergent-ai/surogates","stars":28,"forks":1,"license":"AGPL-3.0","updatedAt":"2026-10-16T18:37:14Z"},"bodyHtml":"<hr>\n<h2>name: docx\ndescription: \"When the office_edit tool is available and the document is in the workspace, use the office skill instead: the user watches the edit live. Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx) or Word templates (.dotx). Triggers include: any mention of Microsoft Word Documents, such as 'Word doc', 'word document', '.docx', '.dotx', 'microsoft doc'. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, 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 deliverable as a Word or .docx file (to download, email or print), use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or coding unrelated to document generation.\"\nfallback_for_tools: [office_edit]\nlicense: Proprietary. LICENSE.txt has complete terms</h2>\n<h1>DOCX creation, editing, and analysis</h1>\n<p>A <code>.docx</code> is a ZIP archive of XML files. Choose your approach by task:</p>\n<table>\n<thead>\n<tr>\n<th>Task</th>\n<th>Approach</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><strong>Create</strong> a new document</td>\n<td>Copy <code>scripts/example_doc.js</code>, replace its content, run it — see below</td>\n</tr>\n<tr>\n<td><strong>Edit</strong> an existing document</td>\n<td><code>unzip</code> → edit <code>word/document.xml</code> → <code>zip</code> (docx-js cannot open existing files)</td>\n</tr>\n<tr>\n<td><strong>Read</strong> content</td>\n<td><code>read_file(path=\"file.docx\")</code> — the harness parses it natively into markdown (headings, paragraphs, lists, tables)</td>\n</tr>\n<tr>\n<td><strong>Read</strong> tracked changes or comments</td>\n<td><code>pandoc --track-changes=all -t markdown file.docx</code> (<code>read_file</code> shows the accepted text only)</td>\n</tr>\n</tbody>\n</table>\n<blockquote>\n<p>Script paths below are relative to this skill's directory — the <code>staged_at</code> path <code>skill_view</code> returns.</p>\n</blockquote>\n<p>Everything this skill uses is preinstalled in the sandbox. The sandbox runs as a non-root user without <code>sudo</code>, so <code>apt-get install</code> always fails; if a CLI tool is missing, use the Python or JavaScript route on this page instead.</p>\n<h2>Creating a document</h2>\n<p>Start from <code>scripts/example_doc.js</code>. It is a one-page agreement that passes <code>validate.py</code>, and it already has everything most documents need: US Letter, the font and size set once for the whole document, numbered clauses with (a)/(b) sub-clauses, bullets, a table, a signature table and a \"Page X of Y\" footer.</p>\n<pre><code>cp scripts/example_doc.js make_doc.js   # into the workspace\n# edit make_doc.js: replace the CONTENT array, nothing else\nnode make_doc.js out.docx\n</code></pre>\n<p><code>docx</code> is preinstalled: do not run <code>npm install</code>.</p>\n<p>Build CONTENT from the helpers the script defines:</p>\n<table>\n<thead>\n<tr>\n<th>Helper</th>\n<th>Produces</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>title(\"TEXT\")</code></td>\n<td>centred bold title</td>\n</tr>\n<tr>\n<td><code>heading(\"Text\")</code></td>\n<td>bold section heading (appears in a TOC)</td>\n</tr>\n<tr>\n<td><code>para(\"Text with **bold**\")</code></td>\n<td>plain paragraph; <code>**…**</code> marks bold</td>\n</tr>\n<tr>\n<td><code>clause(\"**Term.** Text\")</code></td>\n<td>numbered clause: 1. 2. 3.</td>\n</tr>\n<tr>\n<td><code>clause(\"text\", 1)</code></td>\n<td>lettered sub-clause under the clause above: (a) (b)</td>\n</tr>\n<tr>\n<td><code>bullet(\"text\")</code></td>\n<td>bullet item</td>\n</tr>\n<tr>\n<td><code>table(header, rows, [5, 2, 2])</code></td>\n<td>grid table; the widths are relative, the script converts them</td>\n</tr>\n<tr>\n<td><code>signatures([\"Party A\", \"Party B\"])</code></td>\n<td>signature block: Signature / Name / Title / Date lines per party</td>\n</tr>\n</tbody>\n</table>\n<p>Write a blank to fill in as underscores in the text (<code>\"____________\"</code>), as the example does. Change the helpers or the <code>Document</code> options only when the content needs something they cannot express. For A4, set <code>PAGE</code> to <code>{ width: 11906, height: 16838 }</code>; the text and table widths follow from <code>PAGE</code> and <code>MARGIN</code>.</p>\n<p>Rules that apply when you go beyond the example:</p>\n<ul>\n<li><strong>Never type numbers or bullets into the text</strong> (<code>\"1. \"</code>, <code>\"(a) \"</code>, <code>\"•\"</code>). Numbering comes from the <code>numbering</code> config (<code>LevelFormat.DECIMAL</code>, <code>LevelFormat.BULLET</code>); a typed number won't renumber and won't indent.</li>\n<li><strong>Set the font and size once</strong> in <code>styles.default.document.run</code>. Don't repeat <code>font</code>/<code>size</code> on every <code>TextRun</code>.</li>\n<li><strong>The table-layout enum is <code>TableLayoutType.FIXED</code>.</strong> docx has no <code>LayoutType</code>.</li>\n<li><strong>Bold in a heading or the title goes on the <code>TextRun</code>.</strong> LibreOffice ignores <code>bold</code> in the Title/Heading styles.</li>\n<li><strong>Landscape:</strong> pass portrait dimensions and <code>orientation: PageOrientation.LANDSCAPE</code> — docx-js swaps width/height internally.</li>\n<li><strong>Tables need dual widths:</strong> set <code>columnWidths</code> on the table AND <code>width</code> on every cell, both in <code>WidthType.DXA</code> (PERCENTAGE breaks in Google Docs). Column widths must sum to the table width.</li>\n<li><strong>Table shading:</strong> use <code>ShadingType.CLEAR</code>, never <code>SOLID</code> (renders black).</li>\n<li><strong><code>ImageRun</code> requires <code>type:</code></strong> (<code>\"png\"</code>, <code>\"jpg\"</code>, …).</li>\n<li><strong><code>PageBreak</code> must be inside a <code>Paragraph</code>.</strong></li>\n<li><strong>Never use <code>\\n</code></strong> — use separate <code>Paragraph</code> elements.</li>\n<li><strong>TOC:</strong> headings must use built-in <code>HeadingLevel.*</code>; custom heading styles need <code>outlineLevel</code> set or they won't appear.</li>\n<li><strong>Don't use a table as a horizontal rule</strong> — use a paragraph bottom border instead.</li>\n<li><strong>Consecutive paragraphs with identical borders merge into one box</strong> — Word and LibreOffice draw only the group's outer edges, so four bottom-bordered \"Signature: / Name: / Title: / Date:\" paragraphs show a single rule. Give each signature line its own table cell with a bottom border, as <code>signatures()</code> does.</li>\n<li><strong>Dot-leader / right-aligned-on-same-line:</strong> use <code>PositionalTab</code> (<code>alignment: PositionalTabAlignment.RIGHT</code>, <code>leader: PositionalTabLeader.DOT</code>) inside a <code>TextRun</code>, not literal <code>.</code> or space padding.</li>\n</ul>\n<h2>Verify the output</h2>\n<p>After writing a <code>.docx</code>, convert it to PDF and check the facts with text tools first:</p>\n<pre><code>python scripts/office/soffice.py --headless --convert-to pdf output.docx\npdfinfo output.pdf | grep -E 'Pages|Page size'   # page count and paper size\npdftotext -layout output.pdf - | head -120       # the text in reading order, with its numbering\n</code></pre>\n<p>These two are exact. Answer page count, wording, numbering, order and \"is everything there\" from them, not from images.</p>\n<p>Then look at the pages once, for what only an image shows: alignment, table borders, spacing, overlapping text.</p>\n<pre><code>pdftoppm -jpeg -r 100 output.pdf page\nls -1 \"$PWD\"/page-*.jpg\n</code></pre>\n<p>Ask <code>vision_analyze</code> about each image <code>ls</code> printed, once per page (it reads workspace files only — render into the workspace, never <code>/tmp</code>). It misreads small text and miscounts rows, so don't ask it what <code>pdftotext</code> already answered, and don't re-ask the same question at a higher resolution.</p>\n<p><code>pdftoppm</code> zero-pads page numbers to the width of the page count (<code>page-01.jpg</code>…<code>page-12.jpg</code>).</p>\n<p><strong>Fitting a page limit.</strong> If <code>pdfinfo</code> shows too many pages, make these changes in order, re-checking <code>pdfinfo</code> after each:</p>\n<ol>\n<li>Shorten the wording.</li>\n<li>Lower the paragraph spacing in <code>styles.default.document.paragraph.spacing.after</code> (120 → 60).</li>\n<li>Lower <code>SIZE</code> to 20 (10 pt). Never below 20.</li>\n<li>Lower <code>MARGIN</code> to 1080 (0.75″). Never below 1080.</li>\n</ol>\n<p>Never set line spacing below single (<code>spacing.line</code> under 240): the lines overlap.</p>\n<p>Arial, Calibri, Cambria, Times New Roman and Courier New render true-to-width here (metric-compatible stand-ins), so pagination matches Word's to within a line or so. Other fonts are approximated — leave a few lines of slack when the page count matters.</p>\n<h2>Editing existing documents</h2>\n<p>Legacy <code>.doc</code> files must be converted first: <code>python scripts/office/soffice.py --headless --convert-to docx file.doc</code>.</p>\n<pre><code>unzip -q doc.docx -d unpacked/\nfind unpacked -type l -delete   # strip symlink entries — docx from external parties is untrusted\npython scripts/merge_runs.py unpacked/   # coalesce fragmented runs so text is findable\n# edit unpacked/word/document.xml in place — do NOT reformat or pretty-print\n(cd unpacked &amp;&amp; rm -f ../out.docx &amp;&amp; zip -Xr ../out.docx .)\npython scripts/office/validate.py out.docx --original doc.docx   # XSD checks; --auto-repair fixes common issues\n# redlining? add --author \"&lt;the name you redlined under&gt;\" to check every edit is tracked\n</code></pre>\n<p>Word splits text across many <code>&lt;w:r&gt;</code> 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. <code>merge_runs.py</code> merges adjacent identically-formatted runs in <code>word/document.xml</code> without changing content or rendering; it also accepts a <code>.docx</code> directly (<code>python scripts/merge_runs.py doc.docx -o merged.docx</code>).</p>\n<p><strong>Tracked changes:</strong> when redlining, validate with <code>--author \"&lt;the name you redlined under&gt;\"</code> (needs <code>--original</code>) — it reports any text you changed without a <code>&lt;w:ins&gt;</code>/<code>&lt;w:del&gt;</code> around it, which is easy to do by accident and invisible in the accepted view. Wrap runs in <code>&lt;w:ins&gt;</code>/<code>&lt;w:del&gt;</code> with <code>w:id</code>, <code>w:author</code>, <code>w:date</code> attributes. Inside <code>&lt;w:del&gt;</code>, the text element is <code>&lt;w:delText&gt;</code>, not <code>&lt;w:t&gt;</code>. A deleted paragraph mark (<code>&lt;w:pPr&gt;&lt;w:rPr&gt;&lt;w:del w:id=\"..\" w:author=\"..\" w:date=\"..\"/&gt;&lt;/w:rPr&gt;&lt;/w:pPr&gt;</code>) means \"merge this paragraph into the next\" — so deleting a paragraph outright is that plus a <code>&lt;w:del&gt;</code> around every run. The <code>&lt;w:del/&gt;</code> must come before the rPr's other children; their order is schema-enforced.</p>\n<p>To produce a clean copy with all tracked changes accepted: <code>python scripts/accept_changes.py in.docx out.docx</code>.</p>\n<p>Accepting a deleted paragraph mark should join that paragraph to the one below it, so a paragraph whose runs are <em>all</em> deleted vanishes. Word does this; <code>accept_changes.py</code> and <code>pandoc --track-changes=accept</code> don't always. Both fail the same way — they strip the deleted text but leave the emptied paragraph behind, which reads as a stray empty bullet when it was auto-numbered:</p>\n<ul>\n<li><code>pandoc --track-changes=accept</code> never joins the paragraphs.</li>\n<li><code>accept_changes.py</code> (LibreOffice) joins them correctly, except when the deleted paragraph is followed by an empty spacer paragraph.</li>\n</ul>\n<p>An empty bullet in either view is an artifact of that view, not a defect in the document. Check paragraph deletions in the XML.</p>\n<h2>Comments</h2>\n<p>Comments require six cross-linked files. Use the helper — directory mode when you'll also be editing <code>document.xml</code> (saves an unzip/rezip cycle), <code>.docx</code>-direct mode otherwise:</p>\n<pre><code># Against an already-unpacked directory (preferred when also placing markers)\npython scripts/comment.py unpacked/ \"Fees &amp; expenses cap is too low\"\npython scripts/comment.py unpacked/ \"Agreed\" --parent 0\n\n# Against a .docx directly\npython scripts/comment.py contract.docx \"This cap is too low\" -o annotated.docx\n</code></pre>\n<p>The script writes <code>comments.xml</code>, <code>commentsExtended.xml</code>, <code>commentsIds.xml</code>, <code>commentsExtensible.xml</code>, the relationships, and the content-type overrides. Comment IDs are auto-assigned. It then prints the <code>&lt;w:commentRangeStart&gt;</code>/<code>&lt;w:commentRangeEnd&gt;</code>/<code>&lt;w:commentReference&gt;</code> snippet to add to <code>word/document.xml</code> so the comment anchors to specific text — until you place those markers, the comment exists but is not visible.</p>\n<h2>Dependencies</h2>\n<p><code>docx</code> (npm, preinstalled — install only if <code>require('docx')</code> fails) · <code>defusedxml</code>, <code>lxml</code> (pip — merge_runs, comment, validate) · <code>pandoc</code> · <code>zip</code> / <code>unzip</code> · LibreOffice (<code>soffice</code>) · <code>pdftoppm</code> (Poppler)</p>\n","files":[{"path":"LICENSE.txt","sizeBytes":1467,"isText":true},{"path":"scripts/accept_changes.py","sizeBytes":4051,"isText":true},{"path":"scripts/comment.py","sizeBytes":14054,"isText":true},{"path":"scripts/example_doc.js","sizeBytes":6993,"isText":true},{"path":"scripts/__init__.py","sizeBytes":1,"isText":true},{"path":"scripts/merge_runs.py","sizeBytes":9398,"isText":true},{"path":"scripts/office/helpers/__init__.py","sizeBytes":3380,"isText":true},{"path":"scripts/office/helpers/pptx_chart.py","sizeBytes":6441,"isText":true},{"path":"scripts/office/helpers/pptx_slide.py","sizeBytes":1675,"isText":true},{"path":"scripts/office/helpers/pptx_theme.py","sizeBytes":3510,"isText":true},{"path":"scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd","sizeBytes":1963,"isText":false},{"path":"scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd","sizeBytes":2515,"isText":false},{"path":"scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd","sizeBytes":2856,"isText":false},{"path":"scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd","sizeBytes":1344,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd","sizeBytes":6956,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd","sizeBytes":74984,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd","sizeBytes":51302,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd","sizeBytes":624,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd","sizeBytes":152039,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd","sizeBytes":1231,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd","sizeBytes":8862,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd","sizeBytes":14795,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd","sizeBytes":83612,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd","sizeBytes":1269,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd","sizeBytes":7328,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd","sizeBytes":6382,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd","sizeBytes":1248,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd","sizeBytes":880,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd","sizeBytes":2608,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd","sizeBytes":3507,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd","sizeBytes":7507,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd","sizeBytes":23313,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd","sizeBytes":1367,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd","sizeBytes":242277,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd","sizeBytes":26148,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd","sizeBytes":25279,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd","sizeBytes":535,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd","sizeBytes":5712,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd","sizeBytes":4010,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd","sizeBytes":171367,"isText":false},{"path":"scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd","sizeBytes":4646,"isText":false},{"path":"scripts/office/schemas/mce/mc.xsd","sizeBytes":3127,"isText":false},{"path":"scripts/office/schemas/microsoft/wml-2010.xsd","sizeBytes":26549,"isText":false},{"path":"scripts/office/schemas/microsoft/wml-2012.xsd","sizeBytes":3745,"isText":false},{"path":"scripts/office/schemas/microsoft/wml-2018.xsd","sizeBytes":901,"isText":false},{"path":"scripts/office/schemas/microsoft/wml-cex-2018.xsd","sizeBytes":1778,"isText":false},{"path":"scripts/office/schemas/microsoft/wml-cid-2016.xsd","sizeBytes":1002,"isText":false},{"path":"scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd","sizeBytes":600,"isText":false},{"path":"scripts/office/schemas/microsoft/wml-symex-2015.xsd","sizeBytes":745,"isText":false},{"path":"scripts/office/soffice.py","sizeBytes":5945,"isText":true},{"path":"scripts/office/validate.py","sizeBytes":6142,"isText":true},{"path":"scripts/office/validators/base.py","sizeBytes":33721,"isText":true},{"path":"scripts/office/validators/docx.py","sizeBytes":17482,"isText":true},{"path":"scripts/office/validators/__init__.py","sizeBytes":336,"isText":true},{"path":"scripts/office/validators/pptx.py","sizeBytes":15981,"isText":true},{"path":"scripts/office/validators/redlining.py","sizeBytes":18017,"isText":true},{"path":"scripts/templates/commentsExtended.xml","sizeBytes":2611,"isText":false},{"path":"scripts/templates/commentsExtensible.xml","sizeBytes":2707,"isText":false},{"path":"scripts/templates/commentsIds.xml","sizeBytes":2619,"isText":false},{"path":"scripts/templates/comments.xml","sizeBytes":2603,"isText":false},{"path":"scripts/templates/people.xml","sizeBytes":115,"isText":false},{"path":"SKILL.md","sizeBytes":10925,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-17T09:13:33.426946Z","sha256":"17DAC2CCA7134B676F3B34C26AC324A900218AF5A68828FFD427D5C018A92AFE","sizeBytes":166251},"review":null,"source":{"repositoryUrl":"https://github.com/invergent-ai/surogates","path":"skills/productivity/docx","license":"AGPL-3.0","commit":"f423b85eed3b230f0085ed007adc86e8aa639d02","subtreeSha":"692B8774D995A59FFCC05AE28906B427F3BD981EB8810D406A2EE6975C640E25","lastSyncedAt":"2026-10-17T09:13:07.689271Z"},"reviewedAt":"2026-10-17T09:18:03.661744Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/invergent-ai/surogates/tree/master/skills/productivity/docx"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install invergent-ai-surogates@llmmart"},{"target":"git","command":"git clone https://github.com/invergent-ai/surogates.git"}]}