docx-toolkit

Imported from borghei/claude-skills (documents/docx-toolkit/SKILL.md). Install upstream with npx skills add borghei/claude-skills --skill docx-toolkit. Copyright stays with the author (MIT + Commons Clause).

Docx Toolkit

Audit .docx files using the standard library only — no python-docx required. Reads OOXML directly with zipfile + xml.etree.

Table of Contents

• Keywords
• Quick Start
• Core Workflows
• Tools
• Reference Guides
• Templates
• Best Practices
• Scope & Limitations

Keywords

docx, Word, Microsoft Word, document, document review, comments, tracked changes, redline, headings, style guide, word count, document audit

Clarify First

Before running the audit, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

• Audit purpose (pre-handoff cleanup, contract-review triage, or style-guide enforcement): selects the workflow and the thresholds you apply.
• Recipient (external customer, opposing counsel, internal): sets the tolerance for leftover comments and tracked changes.
• Allowed style set (for style-guide enforcement): defines what counts as a non-conforming style.

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Quick Start

python scripts/docx_auditor.py contract.docx

Outputs: word count, paragraph count, heading hierarchy, comment count, tracked-changes status, hyperlink count, list of unique paragraph styles used.

Core Workflows

Workflow 1: Pre-Handoff Document Audit

Goal: Catch the issues that embarrass a sender — leftover comments, unresolved track changes, broken heading hierarchy — before the document leaves.

Steps:

1. Run: python scripts/docx_auditor.py document.docx
2. Review the audit output:
   • Comment count > 0 → resolve or remove before sending
   • Tracked changes detected → accept or reject before sending
   • Heading-hierarchy gaps (H1 → H3 with no H2) → restructure
   • Style sprawl (more than 8 paragraph styles) → consolidate
3. Re-run until clean

Time Estimate: 5-15 minutes per document.

Workflow 2: Contract Review Triage

Goal: Quantify how much rework a returned contract needs before reading it line-by-line.

Steps:

1. Run audit on the returned .docx
2. Comment count > 20 or tracked-change paragraphs > 30% → expect a heavy review pass; schedule time
3. Comment count < 5 → likely cosmetic; quick turnaround possible
4. Use references/docx_review_checklist.md for the actual content review

Time Estimate: 1 minute per document for triage.

Workflow 3: Style-Guide Enforcement

Goal: Detect documents drifting from your style guide before they ship to a customer.

Steps:

1. Define allowed styles in your style guide (see assets/style_compliance_template.md)
2. Run audit on candidate documents
3. Flag any document using styles outside the allowed set
4. Map non-conforming paragraphs back to standard styles

Time Estimate: 2-5 minutes per document.

Tools

docx_auditor.py

Reads a .docx file as a ZIP archive and parses OOXML directly. No external dependencies.

# Human-readable
python scripts/docx_auditor.py document.docx

# JSON
python scripts/docx_auditor.py document.docx --json

Reports:

• Word and paragraph counts
• Heading hierarchy (with gap detection)
• Number of comments
• Whether tracked changes are present
• Unique paragraph styles used
• Hyperlink count
• Image count
• Table count

Limits: This tool reads existing docx files. For generating docx, use the templates in assets/ and edit in Word, or install python-docx separately.

Reference Guides

• references/docx_review_checklist.md — Pre-handoff checklist; common rework triggers; mistakes that survive automated audits

Templates

• assets/style_compliance_template.md — Format for declaring allowed paragraph styles
• assets/handoff_checklist_template.md — Pre-send checklist with sign-off boxes

Best Practices

• Audit before every external send. A 30-second audit catches 80% of avoidable embarrassment.
• Resolve comments before "Final v3.docx". Files named "final" with active comments are how lawyers get tickled.
• Lock heading hierarchy. H1 → H3 with no H2 breaks navigation, accessibility, and table-of-contents generation.
• Prefer styles over inline formatting. A style change in one place beats hundreds of inline overrides.

Scope & Limitations

In Scope:

• Read-only audit of .docx files with scripts/docx_auditor.py, which parses OOXML with zipfile and xml.etree and needs no third-party package
• Word and paragraph counts, heading hierarchy with gap detection, comment count, tracked-changes detection, paragraph styles in use, and hyperlink, image and table counts
• Three workflows: pre-handoff audit, contract review triage, and style-guide enforcement
• A review checklist and templates for allowed styles and pre-send sign-off

Out of Scope:

• Creating or editing .docx files, including accepting tracked changes or deleting comments; the tool only reads
• Reviewing what a contract says (see legal/contract-review/)
• Writing or editing the document's prose (see marketing/copy-editing/)
• Producing formatted documents from markdown (see markdown-html/md-document/)

Important Caveats:

• The auditor reports counts and structure. It does not render the document, so layout, page breaks and visual formatting are not checked.
• It does not compare styles against your allowed list. Style-guide enforcement means reading its style list against the template in assets/ by hand.
• It does not check cross-references or a table of contents for broken targets.
• The triage thresholds, such as more than 20 comments or style sprawl, are rules of thumb. Content errors like a wrong name, jurisdiction or figure need a human read, as the review checklist states.

Integration Points

• Pairs with legal/ skills for contract redlines
• Pairs with marketing/copywriting/ for content review
• Used by c-level-advisor/board-deck-builder for board-pack documents