/docx

name: docx
description: Create, inspect, and edit `.docx` files safely, including comments and OOXML-preserving changes.
user-invocable: true
disable-model-invocation: false
requires:
  bins:
    - node
  node_modules:
    - docx
    - jszip
    - linkedom
metadata:
  hybridclaw:
    category: office
    install:
      - id: node-libs
        kind: runtime-tools
        label: Install the office Node libraries for host-sandbox agents
    short_description: "DOCX editing."
    tags:
      - office
      - document
      - docx
    related_skills:
      - xlsx

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);
});