How to Automate Word Document Tasks with Claude Skills: The Complete Developer Guide

Claude Skills provides a dedicated docx skill that enables programmatic creation, editing, analysis, and conversion of Microsoft Word documents through JavaScript and Python tool-chains.

The ComposioHQ/awesome-claude-skills repository includes a powerful docx skill that lets you automate Word document tasks with Claude Skills. Whether you need to generate compliance reports, redline contracts, or extract content for analysis, this skill orchestrates industry-standard libraries to manipulate the underlying OOXML format. By leveraging dedicated tool-chains for creation versus editing, Claude delivers precise document automation while preserving formatting integrity and tracked changes.

Understanding the Docx Skill Architecture

The docx skill is defined in document-skills/docx/SKILL.md and implements a unified entry point with specialized workflows. At its foundation lies the OOXML format, which represents Word documents as ZIP archives containing XML parts rather than binary blobs.

The architecture splits functionality across two language stacks:

• JavaScript/TypeScript (docx-js): Optimized for generating new .docx files with declarative component APIs.
• Python (Document library): A thin OOXML wrapper designed for modifying existing documents and raw XML manipulation.

This separation allows Claude to select the optimal tool-chain based on whether you are creating fresh content or manipulating existing file structures.

Creating New Word Documents with Docx-JS

When generating new documents—such as automated reports or templated proposals—the skill routes requests to the docx-js library. This Node.js package abstracts OOXML complexity into readable, component-based code.

Here is how to create a formatted Word document with headings and styled text:

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

const doc = new Document({
  sections: [{
    children: [
      new Paragraph({
        heading: HeadingLevel.TITLE,
        children: [new TextRun({ text: 'Quarterly Report', bold: true, size: 56 })]
      }),
      new Paragraph({
        heading: HeadingLevel.HEADING_1,
        children: [new TextRun('Executive Summary')]
      }),
      new Paragraph('This is the summary of the report.'),
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync('Quarterly_Report.docx', buffer);
});

This example demonstrates the patterns documented in document-skills/docx/docx-js.md, where the library handles ZIP packaging and XML generation automatically.

Editing Existing Documents with Python and OOXML

For modifying existing files, Claude switches to a Python workflow using the Document library. This approach requires unpacking the .docx archive, editing the constituent XML, and repackaging it.

The workflow relies on helper scripts in document-skills/docx/ooxml/scripts/:

1. Execute unpack.py to extract the .docx into a directory of XML files.
2. Load and modify specific XML components using the Document library.
3. Execute pack.py to reassemble the archive.

Here is the complete workflow for adding a paragraph with tracked changes to an existing contract:

from document import Document
import subprocess

# Unpack the .docx (creates a directory with XML parts)

subprocess.run(['python', 'ooxml/scripts/unpack.py', 'contract.docx', 'tmp'])

# Load the document

doc = Document('tmp/word/document.xml')

# Insert a tracked insertion

doc.add_paragraph('New clause: Payment due within 30 days.', style='Normal')
doc.save()

# Re-pack the edited files back into a .docx

subprocess.run(['python', 'ooxml/scripts/pack.py', 'tmp', 'contract_updated.docx'])

According to document-skills/docx/ooxml.md, this method preserves original <w:rsidR> identifiers to maintain unchanged text integrity. The skill enforces batch processing of 3-10 edits per batch to ensure reliable debugging and guaranteed application of every change.

Extracting Content and Converting Formats

Beyond creation and editing, the docx skill enables document analysis and format conversion through external utilities.

Extracting Text with Pandoc

For reading document content while preserving tracked changes, Claude uses pandoc to convert .docx files to Markdown. This exposes revision history through standard markup tags.

pandoc --track-changes=all contract.docx -o contract.md

The resulting Markdown uses <ins> and <del> tags to denote insertions and deletions, allowing Claude to reason about revision history without parsing binary OOXML directly.

Converting Documents to Images

To generate visual previews or enable OCR processing, the skill chains LibreOffice headless conversion with pdftoppm:

# Convert to PDF using headless LibreOffice

soffice --headless --convert-to pdf contract.docx

# Render pages to JPEG at 150 DPI

pdftoppm -jpeg -r 150 contract.pdf page

This produces page-by-page JPEG files as documented in document-skills/docx/SKILL.md, suitable for visual inspection or pipeline processing.

The Workflow Decision Tree

The SKILL.md file implements a decision tree that determines which tool-chain Claude invokes based on your specific request:

• Reading and analyzing → Use Text extraction via pandoc or Raw XML access via unpack.py + ooxml scripts.
• Creating a fresh document → Use docx-js for JavaScript/TypeScript generation.
• Editing an existing file → Use the Python Document library for high-level API changes, or direct OOXML node manipulation for complex structural modifications.

This routing logic ensures optimal tool selection while maintaining consistent output formatting and change tracking.

Summary

• The docx skill in ComposioHQ/awesome-claude-skills provides dual tool-chains for Word automation: JavaScript for creation and Python for editing.
• Docx-js generates new documents using a declarative component API documented in docx-js.md.
• Python Document library edits existing files by manipulating OOXML through ooxml/scripts/unpack.py and pack.py helpers.
• Pandoc enables lossless text extraction including tracked changes, while LibreOffice and pdftoppm handle image conversion workflows.
• The skill processes edits in batches of 3-10 changes to ensure reliability and facilitate debugging.
• All operations preserve OOXML integrity, including revision identifiers (<w:rsidR>) for tracked changes.

Frequently Asked Questions

What dependencies are required to automate Word document tasks with Claude Skills?

The docx skill requires pandoc for Markdown conversion, the docx npm package for JavaScript generation, LibreOffice for PDF rendering, poppler-utils (which provides pdftoppm) for image extraction, and defusedxml for secure Python XML parsing. Claude verifies these packages before executing any workflow to prevent runtime errors.

How does Claude handle tracked changes when editing Word documents?

When editing existing documents, Claude unpacks the .docx archive into its constituent XML parts using ooxml/scripts/unpack.py. It preserves the original <w:rsidR> identifiers to keep unchanged text intact while inserting new tracked changes into the XML structure. After modification, ooxml/scripts/pack.py repackages the files, maintaining the document's revision history and redline capabilities.

Can I use Python to create new Word documents instead of JavaScript?

While the docx skill primarily routes document creation through docx-js (JavaScript), the Python Document library in ooxml.md technically supports creating documents from scratch by building OOXML structures manually. However, the skill's decision tree recommends JavaScript for new documents because the docx-js API provides higher-level abstractions for formatting, styles, and component organization compared to raw OOXML manipulation.

What is the recommended batch size for document edits, and why?

The skill documentation recommends processing 3-10 edits per batch when modifying existing documents. This constraint makes debugging easier by isolating changes, ensures that every modification is correctly applied to the OOXML structure, and prevents XML corruption that can occur when making hundreds of simultaneous edits to complex document hierarchies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}