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

> Discover recommended workflows for editing DOCX documents with Claude Skills. Learn to use pandoc, docx-js, and Python for reproducible document manipulation.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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](https://github.com/ComposioHQ/awesome-claude-skills) repository defines these capabilities in [`document-skills/docx/SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/document-skills/docx/ooxml/scripts/unpack.py). This exposes the underlying XML files including [`word/document.xml`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/word/document.xml) and [`word/comments.xml`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/document-skills/docx/docx-js.md) reference to ensure compliance with syntax rules and formatting constraints. The implementation builds a hierarchical structure:

```typescript
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.

```python
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/docx-js.md) or [`ooxml.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/ooxml/scripts/unpack.py) exposes [`word/document.xml`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/document-skills/docx/SKILL.md) within the [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) repository. This file contains the "GOOD" versus "BAD" editing examples, the full redlining procedure, and references to [`docx-js.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/docx-js.md) and [`ooxml.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/ooxml.md).