docx

name	docx
description	Work with Word documents (DOCX/DOC) - read, extract content, create documents, convert formats, and process templates. Use when the user asks to work with Word files or .docx documents.
allowed-tools	Read, Bash, Write

Word Document (DOCX) Processing Skill

When working with Word documents, follow these guidelines:

1. Reading & Extracting from DOCX

Extract text content:

# Using pandoc
pandoc document.docx -t plain -o output.txt

# Using python-docx
python3 -c "
import docx
doc = docx.Document('document.docx')
for para in doc.paragraphs:
    print(para.text)
"

# Using antiword (for .doc files)
antiword document.doc > output.txt

Extract with formatting:

# Convert to markdown (preserves structure)
pandoc document.docx -t markdown -o output.md

# Convert to HTML
pandoc document.docx -t html -o output.html

Extract images:

# DOCX files are ZIP archives
unzip -j document.docx 'word/media/*' -d extracted_images/

# Or using python
python3 << 'EOF'
import docx
import os

doc = docx.Document('document.docx')
os.makedirs('images', exist_ok=True)

for i, rel in enumerate(doc.part.rels.values()):
    if "image" in rel.target_ref:
        img = rel.target_part.blob
        with open(f'images/image_{i}.png', 'wb') as f:
            f.write(img)
EOF

2. Creating DOCX Files

From plain text:

# Using pandoc
pandoc input.txt -o output.docx

From markdown:

# Basic conversion
pandoc input.md -o output.docx

# With custom styling
pandoc input.md --reference-doc=template.docx -o output.docx

From HTML:

pandoc input.html -o output.docx

Using Python:

from docx import Document
from docx.shared import Inches, Pt
from docx.enum.text import WD_ALIGN_PARAGRAPH

# Create new document
doc = Document()

# Add heading
doc.add_heading('Document Title', 0)

# Add paragraph
p = doc.add_paragraph('This is a paragraph with ')
p.add_run('bold').bold = True
p.add_run(' and ')
p.add_run('italic').italic = True
p.add_run(' text.')

# Add table
table = doc.add_table(rows=3, cols=3)
table.style = 'Light Grid Accent 1'

# Add image
doc.add_picture('image.png', width=Inches(4))

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

3. Converting DOCX

DOCX to PDF:

# Using LibreOffice (headless)
libreoffice --headless --convert-to pdf document.docx

# With output directory
libreoffice --headless --convert-to pdf --outdir ./output document.docx

# Using pandoc (requires LaTeX)
pandoc document.docx -o output.pdf

DOCX to HTML:

# Using pandoc
pandoc document.docx -o output.html

# With standalone HTML
pandoc document.docx -s -o output.html

DOCX to Markdown:

# Clean markdown output
pandoc document.docx -t markdown -o output.md

# GitHub-flavored markdown
pandoc document.docx -t gfm -o output.md

DOC to DOCX:

# Using LibreOffice
libreoffice --headless --convert-to docx document.doc

4. Template Processing

Mail merge / Variable substitution:

from docx import Document

def fill_template(template_path, output_path, data):
    doc = Document(template_path)

    # Replace in paragraphs
    for paragraph in doc.paragraphs:
        for key, value in data.items():
            if f'{{{key}}}' in paragraph.text:
                paragraph.text = paragraph.text.replace(f'{{{key}}}', str(value))

    # Replace in tables
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for key, value in data.items:
                    if f'{{{key}}}' in cell.text:
                        cell.text = cell.text.replace(f'{{{key}}}', str(value))

    doc.save(output_path)

# Usage
data = {
    'name': 'John Doe',
    'date': '2026-01-22',
    'company': 'Acme Corp'
}
fill_template('template.docx', 'output.docx', data)

5. Analyzing DOCX Structure

Get document stats:

from docx import Document

doc = Document('document.docx')

print(f"Paragraphs: {len(doc.paragraphs)}")
print(f"Tables: {len(doc.tables)}")
print(f"Sections: {len(doc.sections)}")

# Word count
text = ' '.join([p.text for p in doc.paragraphs])
print(f"Words: {len(text.split())}")

Extract all headings:

from docx import Document

doc = Document('document.docx')

for para in doc.paragraphs:
    if para.style.name.startswith('Heading'):
        print(f"{para.style.name}: {para.text}")

List styles used:

from docx import Document

doc = Document('document.docx')
styles = set(p.style.name for p in doc.paragraphs)
print("Styles used:", styles)

6. Modifying Existing DOCX

Add content to existing document:

from docx import Document

doc = Document('existing.docx')

# Add new paragraph
doc.add_paragraph('New paragraph added')

# Add page break
doc.add_page_break()

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

Replace text globally:

from docx import Document

def replace_text(doc_path, search, replace):
    doc = Document(doc_path)

    for paragraph in doc.paragraphs:
        if search in paragraph.text:
            paragraph.text = paragraph.text.replace(search, replace)

    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                if search in cell.text:
                    cell.text = cell.text.replace(search, replace)

    doc.save(doc_path)

7. Working with Tables

Extract table data:

from docx import Document

doc = Document('document.docx')

for i, table in enumerate(doc.tables):
    print(f"\nTable {i+1}:")
    for row in table.rows:
        cells = [cell.text for cell in row.cells]
        print('\t'.join(cells))

Create formatted table:

from docx import Document

doc = Document()

# Create table
table = doc.add_table(rows=1, cols=3)
table.style = 'Light List Accent 1'

# Header row
header_cells = table.rows[0].cells
header_cells[0].text = 'Name'
header_cells[1].text = 'Age'
header_cells[2].text = 'City'

# Data rows
data = [
    ('John', '30', 'New York'),
    ('Jane', '25', 'London')
]

for name, age, city in data:
    row = table.add_row().cells
    row[0].text = name
    row[1].text = age
    row[2].text = city

doc.save('table.docx')

8. Common Workflows

Create report from data

# Generate from JSON data
python3 << 'EOF'
import json
from docx import Document
from docx.shared import Inches

# Load data
with open('data.json') as f:
    data = json.load(f)

# Create document
doc = Document()
doc.add_heading(data['title'], 0)

for section in data['sections']:
    doc.add_heading(section['heading'], 1)
    doc.add_paragraph(section['content'])

doc.save('report.docx')
EOF

Batch convert DOC to DOCX

# Convert all .doc files in directory
for file in *.doc; do
    libreoffice --headless --convert-to docx "$file"
done

Extract all links

from docx import Document

doc = Document('document.docx')

for paragraph in doc.paragraphs:
    for run in paragraph.runs:
        if run.font.underline and 'http' in run.text:
            print(run.text)

Tools Required

Install necessary tools:

Linux (Ubuntu/Debian):

sudo apt-get install pandoc libreoffice python3-pip antiword
pip3 install python-docx

macOS:

brew install pandoc libreoffice
pip3 install python-docx

Windows:

# Install Pandoc and LibreOffice manually
pip install python-docx

Security Notes

• ✅ Validate file paths before processing
• ✅ Check file sizes to prevent memory issues
• ✅ Sanitize user input in templates
• ✅ Be cautious with macro-enabled documents (.docm)
• ✅ Scan documents from untrusted sources
• ✅ Don't execute embedded scripts automatically

When to Use This Skill

Use /docx when the user:

• Wants to read or extract text from Word documents
• Needs to create DOCX files from templates or data
• Wants to convert DOCX to other formats (PDF, HTML, Markdown)
• Asks to process mail merge or template variables
• Needs to extract tables, images, or structure from documents
• Wants to batch process multiple Word files
• Asks to modify existing Word documents

Always confirm before overwriting existing files.