How to Access Raw XML for DOCX Files Using Awesome Claude Skills

Access raw XML in DOCX files by unpacking the archive with the repository's utility scripts, editing the XML contents directly (such as word/document.xml), and repacking the folder structure back into a valid DOCX document.

DOCX files are fundamentally ZIP archives containing structured XML documents according to the Office Open XML (OOXML) specification. The Awesome Claude Skills repository provides specialized tooling in document-skills/docx/ that exposes this underlying XML structure, allowing you to access and manipulate raw document data when high-level APIs prove insufficient.

Understanding the DOCX File Structure

Before accessing raw XML, you must understand how DOCX files organize their content. According to the repository's OOXML documentation, a DOCX file is simply a ZIP archive containing XML files and media resources that follow a strict directory structure.

What is OOXML?

Office Open XML (OOXML) is the standardized XML-based file format used by Microsoft Word. As documented in [ooxml.md](https://github.com/ComposioHQ/awesome-claude-skills/blob/master/document-skills/docx/ooxml.md), the DOCX format stores document content, styles, relationships, and media as separate XML files within a ZIP container. The primary content resides in word/document.xml, while supporting files handle styles (word/styles.xml), relationships (word/_rels/document.xml.rels), and document properties.

Why Access Raw XML?

While the repository's Document class handles common operations automatically, you need raw XML access for complex customizations. The skill documentation in [SKILL.md](https://github.com/ComposioHQ/awesome-claude-skills/blob/master/document-skills/docx/SKILL.md) explicitly supports "Raw XML access" for edge cases like bespoke hyperlink attributes, unusual bookmark structures, or direct manipulation of table properties that high-level abstraction layers cannot reach.

Unpacking DOCX Files to Access Raw XML

To access the raw XML, you must first unpack the DOCX archive into its constituent files. The repository provides a dedicated utility script for this operation.

Use the unpack script located at document-skills/docx/ooxml/scripts/unpack.py to extract the archive:

python ooxml/scripts/unpack.py myfile.docx unpacked/

This command creates an unpacked/ directory containing the full OOXML structure, including the word/ subdirectory where document.xml and other content files reside. After unpacking, you can access any XML file directly using standard text editors or XML parsers.

Reading and Editing XML Content

Once unpacked, you can read and modify the raw XML using Python's XML libraries or the repository's Document class.

Using Python and defusedxml

For security-conscious XML parsing, use the defusedxml library to parse the raw document structure:

from defusedxml.minidom import parse

# Load the main document XML

doc_xml = parse('unpacked/word/document.xml')
print(doc_xml.toprettyxml())

This approach gives you full DOM access to nodes, allowing you to search for specific elements, modify attributes, or inject custom XML structures.

Using the Document Class

The repository's [scripts/document.py](https://github.com/ComposioHQ/awesome-claude-skills/blob/master/document-skills/docx/scripts/document.py) provides a high-level Document class that manages the XML files while still exposing raw editing capabilities. The class loads the unpacked directory and provides dictionary-style access to individual XML files:

from scripts.document import Document

doc = Document('unpacked')
xml_editor = doc["word/document.xml"]
print(xml_editor.tostring())

The Document class tracks changes to XML files and manages relationships between document parts, ensuring that modifications to raw XML remain valid within the OOXML ecosystem.

Direct XML Manipulation

For precise control, edit the XML files directly. The main content in word/document.xml uses the w: namespace for Word processing elements. You can append raw XML fragments using the editor's insertion methods:

# Insert a custom paragraph after an existing node

target = doc["word/document.xml"].get_node(tag="w:p", contains="Introduction")
new_xml = """<w:p>
  <w:r>
    <w:t>Content added via raw XML</w:t>
  </w:r>
</w:p>"""
doc["word/document.xml"].insert_after(target, new_xml)

Repacking XML into DOCX

After modifying the raw XML, you must repack the directory structure into a valid DOCX file. The [ooxml/scripts/pack.py](https://github.com/ComposioHQ/awesome-claude-skills/blob/master/document-skills/docx/ooxml/scripts/pack.py) script handles this compression while maintaining OOXML compliance:

python ooxml/scripts/pack.py unpacked/ modified.docx

This command creates modified.docx, a fully functional Word document containing your XML modifications. The resulting file maintains compatibility with Microsoft Word, LibreOffice, and other OOXML-aware applications.

Complete Workflow Examples

Python API Workflow

The following example demonstrates the complete workflow using the Document class to access and modify raw XML programmatically:

from scripts.document import Document

# Load and automatically unpack

doc = Document('source.docx')

# Access raw XML content

xml_content = doc["word/document.xml"].tostring()

# Find and modify specific nodes

node = doc["word/document.xml"].get_node(tag="w:t", contains="Old Text")
if node:
    node.firstChild.nodeValue = "Modified via raw XML access"

# Save repacks the archive automatically

doc.save('output.docx')

Command-Line Workflow

For automation scripts or quick edits, use the command-line tools without writing Python code:

# Extract the DOCX

python ooxml/scripts/unpack.py contract.docx workdir/

# Edit XML using sed, awk, or manual editing

sed -i 's/Confidential/PUBLIC/g' workdir/word/document.xml

# Repack to DOCX

python ooxml/scripts/pack.py workdir/ contract-public.docx

Direct File I/O with XML Parsing

For advanced scenarios requiring external XML libraries:

from defusedxml.minidom import parse
import shutil

# Manual file operations

shutil.unpack_archive('document.docx', 'extracted/', 'zip')

# Parse and modify

doc_xml = parse('extracted/word/document.xml')
paragraphs = doc_xml.getElementsByTagName('w:p')

# ... modifications ...

# Write back and repack manually or via pack.py

with open('extracted/word/document.xml', 'w') as f:
    f.write(doc_xml.tostring())

Summary

• DOCX files are ZIP archives containing XML documents structured according to the OOXML specification, as defined in document-skills/docx/ooxml.md.
• Use unpack.py to extract the archive and access files like word/document.xml directly.
• The Document class in scripts/document.py provides managed access to raw XML while handling OOXML relationships and metadata automatically.
• Edit XML directly when you need fine-grained control over document elements, namespaces, or attributes that high-level APIs cannot access.
• Use pack.py to recompress the modified XML structure into a standards-compliant DOCX file.
• Always validate changes against OOXML standards to ensure compatibility with word processors.

Frequently Asked Questions

How do I find specific content within word/document.xml?

Use the get_node method provided by the Document class, which accepts parameters like tag="w:p" and contains="search text" to locate specific XML nodes without manually traversing the DOM. Alternatively, use defusedxml or lxml XPath queries to target elements by attribute or text content.

Can I modify XML files manually with a text editor?

Yes. After running unpack.py, all XML files are plain text in the extracted directory. You can edit word/document.xml, word/styles.xml, or any other file using VS Code, Vim, or any XML-aware editor. When finished, run pack.py to recreate the DOCX archive. Ensure your edits maintain valid XML structure and OOXML namespace declarations.

What is the difference between using the Document class and raw XML parsing?

The Document class manages infrastructure details like RSIDs (revision save IDs), relationship files (_rels/), and people.xml tracking data automatically. Raw XML parsing via defusedxml gives you unrestricted access to the document structure but requires you to manually update relationship files and ensure namespace compliance. Use Document for most operations; drop to raw parsing only for complex structural modifications.

Is it safe to edit DOCX XML manually?

Manual editing is safe if you preserve XML well-formedness and OOXML schema compliance. Always work on copies of original files, validate XML syntax before repacking, and test the resulting DOCX in Microsoft Word or LibreOffice. The repository's pack.py script performs basic validation, but malformed XML may cause Word to enter recovery mode when opening the file.

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