DOCX
Use this skill whenever the user asks to create, revise, comment on, or inspect a .docx document.
Default Workflow
- For new documents with straightforward structure, write Markdown first and convert it with
pandoc.
- For programmatic creation, write a CommonJS
.cjs script and use require("docx"). The container exposes global Node packages through NODE_PATH; avoid bare ESM import "docx" examples.
- For editing an existing
.docx, never round-trip the original file through docx or pandoc. Unpack the OOXML, edit the XML you need, and repack it.
Existing-File Editing Workflow
node skills/office/unpack.cjs input.docx tmp/docx-edit
node skills/office/validate.cjs tmp/docx-edit
node skills/office/pack.cjs tmp/docx-edit output.docx
Edit only the relevant parts under tmp/docx-edit/word/:
document.xml for the main body
styles.xml for styles
numbering.xml for list definitions
header*.xml / footer*.xml for page furniture
_rels/*.rels when you add new parts
Rules
- Preserve existing formatting by editing OOXML directly for in-place revisions.
- Escape XML-sensitive characters (
&, <, >) and preserve xml:space="preserve" when surrounding spaces matter.
- Use DXA table widths and explicit cell widths instead of percentages when layout must survive Word and Google Docs.
- Keep relationship ids, comment ids, and content-type overrides consistent when adding parts.
- Never write plain text or placeholder text directly to a
.docx file path. If generation fails, stop and report the error.
Comments And Reviews
- Use
node skills/docx/scripts/comment.cjs --help to insert a comment around an exact text match inside an unpacked DOCX tree.
- Use
node skills/docx/scripts/accept_changes.cjs /tmp/docx-edit --json to accept straightforward tracked changes after unpacking.
- The helper currently targets
word/document.xml. For complex tracked changes, nested fields, or multi-run matches, edit the OOXML manually after unpacking.
Useful Commands
pandoc draft.docx -t gfm -o draft.md
pandoc outline.md -o report.docx
Templates
- Prefer user-provided
.docx templates from the current workspace for letterhead, memos, and branded report formats.
- Preserve headers, footers, styles, numbering, and section geometry unless the user explicitly asks for a layout change.
Minimal Creation Pattern
const fs = require("node:fs");
const { Document, Packer, Paragraph, TextRun } = require("docx");
const document = new Document({
sections: [
{
children: [
new Paragraph({
children: [new TextRun({ text: "Quarterly Update", bold: true })],
}),
new Paragraph("Prepared for leadership review."),
],
},
],
});
Packer.toBuffer(document).then((buffer) => {
fs.writeFileSync("quarterly-update.docx", buffer);
});
1---2name: docx3description: Create, inspect, and edit `.docx` files safely, including comments and OOXML-preserving changes.4user-invocable: true5disable-model-invocation: false6requires:7 bins:8 - node9 node_modules:10 - docx11 - jszip12 - linkedom13metadata:14 source: https://skillmd.com/skills/hybridaione/docx15 hybridclaw:16 category: office17 install:18 - id: node-libs19 kind: runtime-tools20 label: Install the office Node libraries for host-sandbox agents21 short_description: "DOCX editing."22 tags:23 - office24 - document25 - docx26 related_skills:27 - xlsx28---2930# DOCX3132Use this skill whenever the user asks to create, revise, comment on, or inspect a `.docx` document.3334## Default Workflow3536- For new documents with straightforward structure, write Markdown first and convert it with `pandoc`.37- For programmatic creation, write a CommonJS `.cjs` script and use `require("docx")`. The container exposes global Node packages through `NODE_PATH`; avoid bare ESM `import "docx"` examples.38- For editing an existing `.docx`, never round-trip the original file through `docx` or `pandoc`. Unpack the OOXML, edit the XML you need, and repack it.3940## Existing-File Editing Workflow4142```bash43node skills/office/unpack.cjs input.docx tmp/docx-edit44node skills/office/validate.cjs tmp/docx-edit45node skills/office/pack.cjs tmp/docx-edit output.docx46```4748Edit only the relevant parts under `tmp/docx-edit/word/`:4950- `document.xml` for the main body51- `styles.xml` for styles52- `numbering.xml` for list definitions53- `header*.xml` / `footer*.xml` for page furniture54- `_rels/*.rels` when you add new parts5556## Rules5758- Preserve existing formatting by editing OOXML directly for in-place revisions.59- Escape XML-sensitive characters (`&`, `<`, `>`) and preserve `xml:space="preserve"` when surrounding spaces matter.60- Use DXA table widths and explicit cell widths instead of percentages when layout must survive Word and Google Docs.61- Keep relationship ids, comment ids, and content-type overrides consistent when adding parts.62- Never write plain text or placeholder text directly to a `.docx` file path. If generation fails, stop and report the error.6364## Comments And Reviews6566- Use `node skills/docx/scripts/comment.cjs --help` to insert a comment around an exact text match inside an unpacked DOCX tree.67- Use `node skills/docx/scripts/accept_changes.cjs /tmp/docx-edit --json` to accept straightforward tracked changes after unpacking.68- The helper currently targets `word/document.xml`. For complex tracked changes, nested fields, or multi-run matches, edit the OOXML manually after unpacking.6970## Useful Commands7172```bash73pandoc draft.docx -t gfm -o draft.md74pandoc outline.md -o report.docx75```7677## Templates7879- Prefer user-provided `.docx` templates from the current workspace for letterhead, memos, and branded report formats.80- Preserve headers, footers, styles, numbering, and section geometry unless the user explicitly asks for a layout change.8182## Minimal Creation Pattern8384```js85const fs = require("node:fs");86const { Document, Packer, Paragraph, TextRun } = require("docx");8788const document = new Document({89 sections: [90 {91 children: [92 new Paragraph({93 children: [new TextRun({ text: "Quarterly Update", bold: true })],94 }),95 new Paragraph("Prepared for leadership review."),96 ],97 },98 ],99});100101Packer.toBuffer(document).then((buffer) => {102 fs.writeFileSync("quarterly-update.docx", buffer);103});104```