docx-skill

Create, read, edit, and manipulate Word documents (.docx). Supports text, tables, images, headers, footers, styles, and tracked changes.

weaglewang@weaglewang

Install

openclaw skills install @weaglewang/docx-skill

DOCX Skill v2.0

Overview

Complete Microsoft Word document processing using docx-js library for creation and XML manipulation for editing. A .docx file is a ZIP archive containing XML files.

Installation & Dependencies

Required

bash

# For creating documents
npm install -g docx

# For text extraction
brew install pandoc

# For validation (optional)
pip install python-docx

Optional

bash

# For PDF conversion
brew install --cask libreoffice

# For image processing
brew install imagemagick

Quick Start

Create Your First Document

javascript

const { Document, Packer, Paragraph, TextRun } = require('docx');

const doc = new Document({
  sections: [{
    children: [
      new Paragraph({
        children: [
          new TextRun({ text: "Hello World!", bold: true, size: 32 })
        ]
      })
    ]
  }]
});

await Packer.toBuffer(doc).then(buffer => {
  require('fs').writeFileSync("hello.docx", buffer);
});
console.log("✓ Document created!");

Read Document Content

bash

# Extract text with pandoc
pandoc document.docx -o output.md

# Or with Python
python -c "from docx import Document; doc = Document('file.docx'); print('\n'.join([p.text for p in doc.paragraphs]))"

Complete API Reference

Document Structure

javascript

const { Document, Packer, Section } = require('docx');

const doc = new Document({
  sections: [{
    properties: {
      page: {
        size: { width: 12240, height: 15840 }, // US Letter (DXA units)
        margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch
      }
    },
    children: [/* paragraphs, tables, etc */]
  }]
});

Paragraphs

javascript

const { Paragraph, TextRun, PageBreak } = require('docx');

// Basic paragraph
new Paragraph({
  children: [new TextRun("Simple text")]
})

// Formatted paragraph
new Paragraph({
  children: [
    new TextRun({
      text: "Bold and ",
      bold: true,
      size: 28,  // 14pt (size is half-points)
      font: "Arial"
    }),
    new TextRun({
      text: "italic",
      italics: true,
      color: "FF0000"  // Red in hex
    })
  ],
  spacing: {
    before: 200,   // Space before paragraph
    after: 200,    // Space after paragraph
    line: 360      // Line height (1.5 = 360)
  },
  alignment: "center"  // left, center, right, justified
})

// Heading
new Paragraph({
  heading: "Heading1",
  children: [new TextRun("Chapter Title")]
})

// Page break
new Paragraph({
  children: [new PageBreak()]
})

Lists

javascript

const { LevelFormat } = require('docx');

// Configure numbering in document
const doc = new Document({
  numbering: {
    config: [
      {
        reference: "bullet-list",
        levels: [{
          level: 0,
          format: LevelFormat.BULLET,
          text: "•",
          alignment: "left",
          style: {
            paragraph: { indent: { left: 720, hanging: 360 } }
          }
        }]
      },
      {
        reference: "number-list",
        levels: [{
          level: 0,
          format: LevelFormat.DECIMAL,
          text: "%1.",
          alignment: "left",
          style: {
            paragraph: { indent: { left: 720, hanging: 360 } }
          }
        }]
      }
    ]
  },
  sections: [{
    children: [
      // Bullet list item
      new Paragraph({
        numbering: { reference: "bullet-list", level: 0 },
        children: [new TextRun("Bullet point")]
      }),
      // Numbered list item
      new Paragraph({
        numbering: { reference: "number-list", level: 0 },
        children: [new TextRun("Numbered item")]
      })
    ]
  }]
});

Tables

javascript

const { Table, TableRow, TableCell, WidthType, BorderStyle, ShadingType } = require('docx');

// Create table
new Table({
  width: { size: 9360, type: WidthType.DXA },  // Full content width
  columnWidths: [4680, 4680],  // Two equal columns
  
  rows: [
    // Header row
    new TableRow({
      children: [
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Header 1")] })],
          shading: { fill: "4472C4", type: ShadingType.SOLID },
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        }),
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Header 2")] })],
          shading: { fill: "4472C4", type: ShadingType.SOLID },
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        })
      ]
    }),
    // Data row
    new TableRow({
      children: [
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Data 1")] })],
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        }),
        new TableCell({
          children: [new Paragraph({ children: [new TextRun("Data 2")] })],
          borders: {
            top: { style: BorderStyle.SINGLE, size: 1 },
            bottom: { style: BorderStyle.SINGLE, size: 1 },
            left: { style: BorderStyle.SINGLE, size: 1 },
            right: { style: BorderStyle.SINGLE, size: 1 }
          }
        })
      ]
    })
  ]
})

Images

javascript

const { ImageRun } = require('docx');
const fs = require('fs');

new Paragraph({
  children: [
    new ImageRun({
      type: "png",  // Required: png, jpg, jpeg, gif, bmp, svg
      data: fs.readFileSync("image.png"),
      transformation: {
        width: 400,
        height: 300
      },
      altText: {
        title: "Image Title",
        description: "Image Description",
        name: "image-name"
      }
    })
  ]
})

Headers and Footers

javascript

const { Header, Footer, PageNumber } = require('docx');

const doc = new Document({
  sections: [{
    properties: {
      page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
    },
    headers: {
      default: new Header({
        children: [
          new Paragraph({
            children: [
              new TextRun({ text: "Document Header", bold: true })
            ],
            alignment: "center"
          })
        ]
      })
    },
    footers: {
      default: new Footer({
        children: [
          new Paragraph({
            children: [
              new TextRun("Page "),
              new TextRun({ children: [PageNumber.CURRENT] }),
              new TextRun(" of "),
              new TextRun({ children: [PageNumber.TOTAL_PAGES] })
            ],
            alignment: "center"
          })
        ]
      })
    },
    children: [/* content */]
  }]
});

javascript

const { TableOfContents, HeadingLevel } = require('docx');

const doc = new Document({
  sections: [{
    children: [
      // TOC must come before headings
      new TableOfContents("Table of Contents", {
        hyperlink: true,
        headingStyleRange: "1-3"  // Include H1, H2, H3
      }),
      
      new Paragraph({ children: [new PageBreak()] }),
      
      // Headings for TOC
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("Chapter 1")]
      }),
      new Paragraph({
        heading: HeadingLevel.HEADING_2,
        children: [new TextRun("Section 1.1")]
      })
    ]
  }]
});

Complete Examples

Example 1: Business Report

javascript

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, HeadingLevel, TableOfContents, PageBreak, WidthType } = require('docx');
const fs = require('fs');

const doc = new Document({
  sections: [{
    properties: {
      page: {
        size: { width: 12240, height: 15840 },
        margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }
      }
    },
    children: [
      // Title Page
      new Paragraph({
        children: [
          new TextRun({ text: "Annual Report 2024", bold: true, size: 48, font: "Arial" })
        ],
        spacing: { after: 400 },
        alignment: "center"
      }),
      new Paragraph({
        children: [new TextRun({ text: "Company Name", size: 24 })],
        alignment: "center"
      }),
      new Paragraph({ children: [new PageBreak()] }),
      
      // Table of Contents
      new TableOfContents("Contents", { headingStyleRange: "1-2" }),
      new Paragraph({ children: [new PageBreak()] }),
      
      // Executive Summary
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("Executive Summary")]
      }),
      new Paragraph({
        children: [new TextRun("This report provides an overview of...")]
      }),
      
      // Financial Table
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("Financial Summary")]
      }),
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [3120, 3120, 3120],
        rows: [
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Metric")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("2023")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("2024")] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Revenue")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$10M")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$12M")] })] })
            ]
          })
        ]
      })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync("annual-report.docx", buffer);
  console.log("✓ Report created!");
});

Example 2: Invoice Template

javascript

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, WidthType, BorderStyle } = require('docx');
const fs = require('fs');

const doc = new Document({
  sections: [{
    children: [
      // Header
      new Paragraph({
        children: [new TextRun({ text: "INVOICE", bold: true, size: 36 })],
        alignment: "center",
        spacing: { after: 400 }
      }),
      
      // Invoice Details
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [4680, 4680],
        rows: [
          new TableRow({
            children: [
              new TableCell({
                children: [
                  new Paragraph({ children: [new TextRun({ text: "From:", bold: true })] }),
                  new Paragraph({ children: [new TextRun("Company Name")] }),
                  new Paragraph({ children: [new TextRun("123 Business St")] }),
                  new Paragraph({ children: [new TextRun("city@example.com")] })
                ]
              }),
              new TableCell({
                children: [
                  new Paragraph({ children: [new TextRun({ text: "To:", bold: true })] }),
                  new Paragraph({ children: [new TextRun("Client Name")] }),
                  new Paragraph({ children: [new TextRun("456 Client Ave")] }),
                  new Paragraph({ children: [new TextRun("client@example.com")] })
                ]
              })
            ]
          })
        ]
      }),
      
      new Paragraph({ children: [new TextRun("") ], spacing: { before: 200 } }),
      
      // Invoice Info
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [2340, 2340, 2340, 2340],
        rows: [
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Invoice #", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("INV-2024-001")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Date", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("2024-01-15")] })] })
            ]
          })
        ]
      }),
      
      new Paragraph({ children: [new TextRun("") ], spacing: { before: 400 } }),
      
      // Items Table
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [4680, 2340, 2340],
        rows: [
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Description", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Qty", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Amount", bold: true })] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Web Development")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("40")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$4,000")] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [new Paragraph({ children: [new TextRun("Design")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("20")] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun("$2,000")] })] })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({ children: [] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "Total:", bold: true })] })] }),
              new TableCell({ children: [new Paragraph({ children: [new TextRun({ text: "$6,000", bold: true })] })] })
            ]
          })
        ]
      })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync("invoice.docx", buffer);
  console.log("✓ Invoice created!");
});

Example 3: Resume/CV

javascript

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, WidthType, HeadingLevel } = require('docx');
const fs = require('fs');

const doc = new Document({
  sections: [{
    properties: {
      page: {
        size: { width: 12240, height: 15840 },
        margin: { top: 1000, right: 1000, bottom: 1000, left: 1000 }
      }
    },
    children: [
      // Name and Contact
      new Paragraph({
        children: [new TextRun({ text: "JOHN DOE", bold: true, size: 36, font: "Arial" })],
        alignment: "center"
      }),
      new Paragraph({
        children: [new TextRun("john.doe@email.com | (555) 123-4567 | LinkedIn")],
        alignment: "center",
        spacing: { after: 300 }
      }),
      
      // Experience Section
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("EXPERIENCE")]
      }),
      
      new Table({
        width: { size: 9360, type: WidthType.DXA },
        columnWidths: [2340, 7020],
        rows: [
          new TableRow({
            children: [
              new TableCell({
                children: [new Paragraph({ children: [new TextRun({ text: "2020 - Present", bold: true })] })]
              }),
              new TableCell({
                children: [
                  new Paragraph({ children: [new TextRun({ text: "Senior Developer", bold: true })] }),
                  new Paragraph({ children: [new TextRun("Company Name")] }),
                  new Paragraph({ children: [new TextRun("• Led development of...")] }),
                  new Paragraph({ children: [new TextRun("• Managed team of...")] })
                ]
              })
            ]
          })
        ]
      }),
      
      // Education Section
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("EDUCATION")]
      }),
      new Paragraph({
        children: [
          new TextRun({ text: "Bachelor of Science in Computer Science", bold: true }),
          new TextRun(" | University Name | 2016-2020")
        ]
      }),
      
      // Skills Section
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun("SKILLS")]
      }),
      new Paragraph({
        children: [new TextRun("JavaScript, Python, React, Node.js, SQL, AWS, Docker, Git")]
      })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync("resume.docx", buffer);
  console.log("✓ Resume created!");
});

Editing Existing Documents

Method 1: Unpack → Edit → Repack

bash

# Step 1: Unpack the document
python scripts/office/unpack.py document.docx unpacked/

# Step 2: Edit XML files in unpacked/word/
# Edit document.xml, styles.xml, etc.

# Step 3: Repack
python scripts/office/pack.py unpacked/ output.docx --original document.docx

Method 2: Using python-docx

python

from docx import Document

# Load existing document
doc = Document('existing.docx')

# Read paragraphs
for para in doc.paragraphs:
    print(para.text)

# Edit content
doc.paragraphs[0].text = "New first paragraph"

# Add new paragraph
doc.add_paragraph("New paragraph at end")

# Save
doc.save('edited.docx')

Method 3: Find and Replace

python

from docx import Document

def find_and_replace(doc_path, find_text, replace_text, output_path):
    doc = Document(doc_path)
    
    for para in doc.paragraphs:
        if find_text in para.text:
            para.text = para.text.replace(find_text, replace_text)
    
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                if find_text in cell.text:
                    cell.text = cell.text.replace(find_text, replace_text)
    
    doc.save(output_path)

# Usage
find_and_replace('template.docx', '{{NAME}}', 'John Doe', 'output.docx')

Page Sizes Reference

All sizes in DXA units (1440 DXA = 1 inch):

Paper Size	Width	Height	Use Case
US Letter	12,240	15,840	Default US
A4	11,906	16,838	Default EU
Legal	12,240	20,160	Legal docs
Tabloid	19,840	25,920	Posters
Statement	9,360	12,240	Small docs

Smart Quotes & Special Characters

Use XML entities for professional typography:

Entity	Character	Name
`‘`	'	Left single quote
`’`	'	Right single quote / apostrophe
`“`	"	Left double quote
`”`	"	Right double quote
`–`	–	En dash
`—`	—	Em dash
`©`	©	Copyright
`®`	®	Registered trademark
`™`	™	Trademark

Error Handling

Common Errors

Error: "Font not found"

javascript

// Solution: Use web-safe fonts
new TextRun({ text: "Content", font: "Arial" })  // ✅ Safe
new TextRun({ text: "Content", font: "CustomFont" })  // ❌ May fail

Error: "Image not loading"

javascript

// Solution: Check file path and type
new ImageRun({
  type: "png",  // Must match actual file type
  data: fs.readFileSync("./images/logo.png"),  // Correct path
  transformation: { width: 200, height: 150 }
})

Error: "Table rendering incorrectly"

javascript

// Solution: Set both table width AND cell widths
new Table({
  width: { size: 9360, type: WidthType.DXA },  // Required
  columnWidths: [4680, 4680],  // Required, must sum to table width
  rows: [...]
})

Best Practices

1. Always Set Page Size Explicitly

javascript

// docx-js defaults to A4
properties: {
  page: {
    size: { width: 12240, height: 15840 }  // US Letter
  }
}

2. Use Styles Consistently

javascript

const doc = new Document({
  styles: {
    default: {
      document: {
        run: { font: "Arial", size: 24 }  // 12pt default
      }
    }
  }
});

3. Never Use Unicode Bullets

javascript

// ❌ WRONG
new Paragraph({ children: [new TextRun("• Item")] })

// ✅ CORRECT
new Paragraph({
  numbering: { reference: "bullets", level: 0 },
  children: [new TextRun("Item")]
})

4. Validate Before Distribution

bash

# Check document integrity
python scripts/office/validate.py document.docx

# Or with pandoc
pandoc document.docx -o /dev/null && echo "✓ Valid"

Testing Your Setup

javascript

// test-docx.js
const { Document, Packer, Paragraph, TextRun } = require('docx');
const fs = require('fs');

async function test() {
  console.log("Testing docx setup...");
  
  const doc = new Document({
    sections: [{
      children: [
        new Paragraph({
          children: [new TextRun("Test document created successfully!")]
        })
      ]
    }]
  });
  
  await Packer.toBuffer(doc).then(buffer => {
    fs.writeFileSync("test-output.docx", buffer);
  });
  
  console.log("✓ Test passed! Check test-output.docx");
}

test().catch(console.error);

Run test:

bash

node test-docx.js

License

MIT License - See LICENSE file for details.

docx-skill

Install

DOCX Skill v2.0

Overview

Installation & Dependencies

Required

Optional

Quick Start

Create Your First Document

Read Document Content

Complete API Reference

Document Structure

Paragraphs

Lists

Tables

Images

Headers and Footers

Table of Contents

Complete Examples

Example 1: Business Report

Example 2: Invoice Template

Example 3: Resume/CV

Editing Existing Documents

Method 1: Unpack → Edit → Repack

Method 2: Using python-docx

Method 3: Find and Replace

Page Sizes Reference

Smart Quotes & Special Characters

Error Handling

Common Errors

Error: "Font not found"

Error: "Image not loading"

Error: "Table rendering incorrectly"

Best Practices

1. Always Set Page Size Explicitly

2. Use Styles Consistently

3. Never Use Unicode Bullets

4. Validate Before Distribution

Testing Your Setup

License

Related skills