| name | document-docx |
| description | Create/edit .docx files with styles, templates, comments, and extraction workflows. Use when asked to generate Word reports, contracts, proposals, or convert Word content. |
| allowed-tools | Bash, Read, Write, Glob, Grep |
| compatibility | Claude Code + Codex. Uses runtime-specific allowed-tools / argument-hint fields. |
| version | 1.1 |
| last_validated | 2026-07-11T00:00:00.000Z |
Document DOCX Skill - Quick Reference
This skill covers creation, editing, review, extraction, and release workflows for .docx documents.
Modern best practices (Jul 2026):
- Treat
.docx as the editable source and PDF as a release artifact.
- Prefer templates and built-in styles over manual formatting.
- Use comments for review notes; use Word Compare for true redlines.
- For LLM/RAG extraction, optimize for structure, trust level, and sanitization rather than visual fidelity.
- Treat macro-enabled Office files (
.docm, .dotm) as untrusted by default.
- Before promising a feature (comments, alt text, tracked changes), check the installed library version — several of these APIs are recent additions and silently absent on older pins. See "Version-Gate Before Promising A Feature" below.
Core Decision Rules (2026)
- If non-developers need to own layout/design, prefer
docxtpl with a Word-authored template.
- If the stack is Python and edits are structural, prefer
python-docx.
- If the stack is TypeScript/Node and the output is generated server-side, prefer
docx.
- If you need semantic HTML from a trusted document, prefer
mammoth, then sanitize before rendering or storing the output.
- If you need Markdown/JSON for search, indexing, or RAG, prefer
MarkItDown or Docling.
- If the user asks for tracked changes, do not promise high-level library support. Generate a revised
.docx and use Word Compare, or switch to OOXML-specialized tooling.
- If the user asks for PDF output, prefer Word automation for highest fidelity and LibreOffice headless for cross-platform batch workflows.
- If the input is
.doc, convert to .docx first. If it is .docm or .dotm, do not trust embedded macros.
Quick Reference
| Task | Tool/Library | Language | When to Use |
|---|
| Create/edit DOCX | python-docx | Python | Structural edits, reports, contracts, section/table/image work |
| Create/edit DOCX | docx | Node.js | Server-side generation in TypeScript-heavy stacks |
| Template fill | docxtpl | Python | Word-authored templates, mail merge, batch documents |
| Add/access comments | python-docx + Word review workflow | Python / Word | Review notes without tracked revisions |
| Convert DOCX to HTML | mammoth | Node.js | Semantic HTML from trusted documents |
| Convert DOCX to Markdown | MarkItDown | Python | LLM/RAG ingestion where Markdown is preferred |
| Convert DOCX to Markdown/HTML/JSON | Docling | Python / CLI | Multi-format ingestion, structured extraction, batch conversion |
| Parse text/tables/metadata | python-docx + OOXML inspection | Python | Extraction, audits, migration tooling |
| Parse tracked changes/comments | OOXML, Open XML SDK, docx4j, Aspose.Words | Python / .NET / Java | Revision-heavy workflows and interoperability edge cases |
| Convert DOCX to PDF | Word automation / LibreOffice headless | OS tooling | Release artifacts and cross-platform smoke checks |
Selection Guide
- Prefer
docxtpl when a legal, ops, or business user needs to maintain the template in Word.
- Prefer
python-docx for moderate formatting complexity where you control the document structure in code.
- Prefer
docx when the surrounding service and tests already live in Node.js.
- Prefer
mammoth for trusted, text-first conversion to HTML; it is not a fidelity-preserving renderer.
- Prefer
MarkItDown for simple DOCX-to-Markdown pipelines.
- Prefer
Docling when DOCX is only one input among many formats or you need HTML/JSON/Markdown/text output from a unified pipeline.
ASCII Flow
DOCX request
|
v
Classify file + trust level
|-- .docx / .dotx -----> normal OOXML workflow
|-- .doc -------------> convert to .docx first
|-- .docm / .dotm ----> treat macros as untrusted
|
v
Choose lane
|-- Word-owned template ------> docxtpl
|-- Python structural edit ---> python-docx
|-- Node service generation --> docx
|-- trusted HTML conversion --> mammoth + sanitizer
|-- Markdown / JSON ingest ---> MarkItDown or Docling
|-- tracked-change review ----> revised DOCX + Word Compare
|
v
Generate, edit, or extract
|
v
Quality gate
|-- parseability + unresolved tags ---> scripts/docx_quality_gate.py
|-- comments / revisions / OOXML ----> scripts/docx_inspect_ooxml.py
|
v
Viewer, accessibility, and release checks
Format And Safety Caveats
.docx and .dotx are Office Open XML packages; .doc is legacy binary and needs conversion first..docm and .dotm are macro-enabled; do not treat them as safe content inputs.python-docx can add and read comments in the main document body, but not threaded replies/resolved states, and not comment anchors in headers/footers.python-docx does not provide reliable tracked-change authoring.mammoth performs no sanitization of generated HTML or links from untrusted source documents.- Tables of contents and many Word fields are placeholders until updated in Word.
Version-Gate Before Promising A Feature
Do not assume the environment has a current library. This is the single most common way this skill causes a confident-but-wrong answer:
Document.add_comment() only exists from python-docx 1.2.0 onward. On an older pinned version it raises AttributeError, not a graceful fallback. Check first: python -c "import docx; print(docx.__version__)".- python-docx still has no public high-level property for image alt text (no
.alt_text on InlineShape) as of the current 1.x line — InlineShape only documents height, width, and type. The OOXML workaround in references/accessibility-compliance.md reaches into the private _inline attribute; treat that as an implementation detail that can move between releases, re-verify after any python-docx upgrade, and prefer python-docx's own comment/style APIs wherever a public one exists instead of private attributes.
- If a user asks for a feature this skill flags as unsupported (tracked-change authoring, threaded comment replies, resolved-state comments), say so plainly rather than approximating it with formatting hacks — a document that merely looks right (e.g., colored/struck-through text standing in for
<w:ins>/<w:del>) will fail any real redline/legal review because it carries no revision metadata.
Default Workflow
- Identify the file type and trust level:
.docx/.dotx vs .docm/.dotm vs legacy .doc.
- Pick the lane:
- Template generation ->
docxtpl
- Programmatic structure edits ->
python-docx or docx
- Review/comments -> comments or Word Compare
- LLM extraction ->
MarkItDown, Docling, or mammoth
- Generate or modify the document.
- Run
scripts/docx_quality_gate.py and, when needed, scripts/docx_inspect_ooxml.py.
- If shipping externally, validate rendering in Word plus at least one secondary viewer and apply accessibility hygiene.
Core Operations
Create A Document (Python - python-docx)
from docx import Document
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.shared import Inches
doc = Document()
title = doc.add_heading("Quarterly Review", 0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER
doc.add_paragraph("Executive summary goes here.")
table = doc.add_table(rows=2, cols=2)
table.style = "Table Grid"
table.rows[0].cells[0].text = "Metric"
table.rows[0].cells[1].text = "Value"
table.rows[1].cells[0].text = "Revenue"
table.rows[1].cells[1].text = "$1.2M"
doc.add_picture("chart.png", width=Inches(4.5))
doc.save("quarterly-review.docx")
Add A Review Comment (Python - python-docx)
from docx import Document
doc = Document()
paragraph = doc.add_paragraph("This clause needs legal review.")
comment = doc.add_comment(
runs=paragraph.runs,
text="Clarify whether this applies to renewals as well.",
author="Legal",
initials="LG",
)
comment.paragraphs[0].add_run(" Add the renewal edge case explicitly.").bold = True
doc.save("reviewable.docx")
Fill A Template (Python - docxtpl)
from docxtpl import DocxTemplate
doc = DocxTemplate("template.docx")
context = {
"company_name": "Acme Corp",
"contract_date": "2026-03-13",
"items": [
{"name": "Widget A", "price": 100},
{"name": "Widget B", "price": 200},
],
}
doc.render(context)
doc.save("filled-template.docx")
Convert Trusted DOCX To HTML (Script)
node scripts/docx_to_html.mjs input.docx output.html --style-map custom-style-map.txt --extract-images-dir output-assets/
Extract Structure For Automation (Script)
python3 scripts/docx_extract.py input.docx --include headers footers hyperlinks comments images --out extracted.json
Output Quality Checklist
- Structure: heading hierarchy, list styles, and tables are intentional and consistent.
- Reviewability: comments or Word Compare are used for feedback-heavy workflows instead of ad hoc formatting hacks.
- Safety: macro-enabled files are treated as untrusted; HTML generated from DOCX is sanitized before use.
- Portability: fonts, numbering, tables, and images are checked in at least one non-Word viewer when documents are distributed.
- Accessibility hygiene: headings, descriptive links, table headers, document language, and alt text are present where needed.
- Release quality: run
scripts/docx_quality_gate.py before shipping or batch-publishing.
Optional: AI / Automation
Use only when explicitly requested and policy-compliant.
- Convert trusted DOCX content into Markdown/HTML/JSON for search or RAG.
- Summarize meeting notes into a Word template, but keep humans accountable for factual accuracy.
- Generate first-pass reports/contracts from structured data, then route through human review.
Navigation
Resources
- references/docx-patterns.md - Styles, headers/footers, tables, sections, TOC
- references/template-workflows.md - Template authoring, mail merge, batch rendering
- references/review-comments-workflows.md - Comments, review notes, Word Compare, comment limits
- references/tracked-changes.md - What is and is not feasible for tracked revisions
- references/llm-extraction-workflows.md - Mammoth, MarkItDown, Docling, HTML/Markdown/JSON extraction
- references/accessibility-compliance.md - Word accessibility, EN 301 549 context, manual checks
- references/cross-platform-compatibility.md - Word, Google Docs, LibreOffice, PDF conversion
- references/document-automation-pipelines.md - CI/CD, batch generation, quality gates
- data/sources.json - Current external documentation links
Scripts
scripts/docx_inspect_ooxml.py - Dependency-free OOXML inspection for tracked changes and commentsscripts/docx_extract.py - Extract text, tables, metadata, and optional headers/footers/hyperlinks/comments/images to JSONscripts/docx_render_template.py - Render a docxtpl template from JSONscripts/docx_to_html.mjs - Convert trusted .docx to HTML with style maps and optional image extractionscripts/docx_quality_gate.py - Validate parseability, unresolved template tags, tracked-change/comment signals, and optional LibreOffice conversion
Templates
Related Skills
Fact-Checking
- Use
data/sources.json as the starting set of primary sources.
- Use web search/web fetch to verify current external facts, versions, release behavior, regulations, and platform quirks before final answers.
- Prefer primary documentation, package pages, release pages, and official standards pages.
- If web access is unavailable, state the limitation and mark volatile guidance as unverified.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
