Recommended Workflows for Editing DOCX Documents with Claude Skills: A Complete Technical Guide

Claude Skills provide a structured, reproducible pipeline for reading, creating, and editing Word documents using pandoc, docx-js, and the Python Document library with XML unpacking workflows.

The ComposioHQ/awesome-claude-skills repository defines these capabilities in document-skills/docx/SKILL.md, which establishes a decision tree separating reading, creation, basic editing, and redlining workflows. These recommended workflows for editing DOCX documents with Claude Skills ensure minimal layout corruption while handling complex formatting and tracked changes.

Reading and Extracting Content from DOCX Files

Claude Skills offer two primary methods for document analysis, chosen based on whether you need plain text or raw XML structure.

Text Extraction with Pandoc

For standard content analysis, Claude runs pandoc with the --track-changes flag to preserve revision marks during conversion. This approach renders the document as human-readable text while maintaining visibility of insertions and deletions.

Raw XML Inspection for Complex Formatting

When working with comments, embedded media, or intricate formatting, Claude unpacks the DOCX archive using the Python helper document-skills/docx/ooxml/scripts/unpack.py. This exposes the underlying XML files including word/document.xml and word/comments.xml for direct inspection and manipulation.

Creating New DOCX Documents

For programmatic document generation, the skill mandates the docx-js library (JavaScript/TypeScript) as the recommended engine.

The docx-js Implementation Pattern

Before generating code, Claude must read the complete document-skills/docx/docx-js.md reference to ensure compliance with syntax rules and formatting constraints. The implementation builds a hierarchical structure:

import { Document, Packer, Paragraph, TextRun } from "docx";
import * as fs from "fs";

const doc = new Document({
  sections: [{
    properties: {},
    children: [
      new Paragraph({
        children: [
          new TextRun({
            text: "Executive Summary",
            bold: true,
            size: 32,
          }),
        ],
      }),
      new Paragraph("This agreement is entered into on the 1st of January, 2025."),
      new Paragraph({
        children: [
          new TextRun("Party A:"), new TextRun({ text: " Acme Corp.", underline: {} }),
        ],
      }),
    ],
  }],
});

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

The Packer.toBuffer() method serializes the document hierarchy into a binary buffer suitable for writing to disk.

Basic Editing with the Python Document Library

For straightforward modifications to existing user documents, Claude employs the Document library, a Python OOXML wrapper.

Prerequisites for Safe Editing

The skill requires Claude to read the full document-skills/docx/ooxml/ooxml.md reference (approximately 600 lines) before any edit operation. This ensures familiarity with both high-level helper methods and low-level DOM patterns necessary for safe document manipulation.

Redlining Workflow for Tracked Changes

The redlining workflow serves as the default approach for third-party or legal-style documents requiring tracked-change preservation. This batch-oriented process minimizes corruption risk through precise, incremental edits.

The Six-Step Redlining Process

1. Convert to markdown: Run pandoc --track-changes=all to establish a human-readable baseline of the original DOCX.
2. Unpack the archive: Execute python ooxml/scripts/unpack.py to expose raw XML files.
3. Batch changes: Group edits into logical batches of 3-10 changes, locating exact XML nodes using grep on word/document.xml.
4. Implement edits: Use the Document library with keep_context=True to preserve original <w:r> runs and RSIDs, maintaining unchanged text intact.
5. Repack the document: Run python ooxml/scripts/pack.py to reconstruct the DOCX archive.
6. Verify output: Reconvert the final DOCX to markdown and grep for expected insertions or deletions.

Preserving Document Integrity

The replace() method in the Document library supports a keep_context parameter that maintains surrounding run structures. This prevents the layout corruption common in naive find-and-replace operations.

from document import Document   # provided by the Document library

import os, subprocess, pathlib

# 1️⃣ Unpack the docx

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

# 2️⃣ Load the unpacked XML

doc = Document(pathlib.Path("tmp"))

# 3️⃣ Batch edit – change “30 days” → “60 days” (preserve surrounding runs)

doc.replace(
    old_text="30",
    new_text="60",
    keep_context=True,           # keeps unchanged <w:r> runs and RSID

)

# 4️⃣ Save the modified XML

doc.save()

# 5️⃣ Pack back to .docx

subprocess.run(["python", "ooxml/scripts/pack.py", "tmp", "contract-updated.docx"])

Summary

• Claude DOCX skills provide distinct workflows for reading (pandoc), creating (docx-js), and editing (Python Document library).
• The redlining workflow enforces batched changes with XML unpacking to handle tracked-changes safely.
• Always reference docx-js.md or ooxml.md before generating code to ensure API compliance.
• Use keep_context=True when replacing text to preserve RSIDs and run structures.
• Verify edits by reconverting final documents to markdown and checking for expected changes.

Frequently Asked Questions

What is the difference between the docx-js and Document library approaches?

docx-js is a JavaScript/TypeScript library used exclusively for creating new DOCX files through a declarative API (Document, Paragraph, TextRun). The Document library is a Python wrapper for OOXML used specifically for editing existing documents while preserving their XML structure and tracked changes. According to the source code in document-skills/docx/SKILL.md, these tools serve distinct purposes and are never interchangeable.

How does Claude handle tracked changes when redlining documents?

Claude uses pandoc --track-changes=all during the initial conversion phase to render tracked changes as visible markup, then preserves these changes during editing by maintaining original <w:r> tags and RSID attributes. The verification step requires reconverting the final document to confirm that insertions and deletions remain intact.

Why is unpacking the DOCX archive necessary for complex edits?

DOCX files are ZIP archives containing OOXML files. Unpacking via ooxml/scripts/unpack.py exposes word/document.xml and other components, allowing Claude to use grep for precise node location and the Document library for targeted modifications. This approach prevents the formatting corruption that occurs when high-level APIs attempt to parse complex nested revisions.

Where can I find the complete skill definition for DOCX workflows?

The complete decision tree and workflow specifications reside in document-skills/docx/SKILL.md within the ComposioHQ/awesome-claude-skills repository. This file contains the "GOOD" versus "BAD" editing examples, the full redlining procedure, and references to docx-js.md and ooxml.md.

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