---
name: docx-formatter
description: "Generate Word documents (.docx) with letterhead, tables of contents, page numbers, headers. Outputs properly-formatted .docx files — table of contents, styled headings, page numbers, footnotes, image insertion. Useful for reports, contracts, and letterhead-branded outputs."
license: MIT
---

# DOCX Formatter

DOCX Formatter produces real, well-structured Microsoft Word files (`.docx`) — not Markdown pretending to be a document. It is built for people who need to ship finished deliverables: contracts, board reports, proposals, and letterhead-branded correspondence where heading styles, an auto-numbered table of contents, page numbers, and footnotes actually have to render correctly when the recipient opens the file in Word.

## When to use it

- You asked for a "report," "memo," "contract," or "letter" and the recipient expects an editable `.docx`, not a PDF.
- You need a clickable, auto-updating table of contents driven by real heading styles (Heading 1/2/3).
- You're applying a company letterhead, header/footer, and "Page X of Y" numbering across every page.
- You're editing an existing document — find-and-replace, swapping images, or adding footnotes — without flattening the original styling.

## What it does / how it works

Under the hood the skill works directly with the Office Open XML format. New documents are assembled with a docx generation library so paragraphs carry true style references (`HeadingLevel.HEADING_1`, etc.) rather than manual font sizing — that's what makes the TOC and navigation pane work. A `TableOfContents` field is inserted and marked dirty so Word rebuilds it on open. Headers and footers hold the letterhead and a `PAGE`/`NUMPAGES` field pair for "Page X of Y." Images are embedded as relationships in the package, not linked.

For editing existing files, it manipulates the unzipped `word/document.xml` and related parts, preserving styles. Conversion to and from other formats (Markdown, HTML) goes through Pandoc when needed. Tracked-changes (redlining) and comments are supported by writing the appropriate `w:ins`/`w:del` and comment parts.

## Usage example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/docx-formatter/SKILL.md https://claudeskil.com/skills/docx-formatter/SKILL.md

# then, in a Claude session:
"Generate a Q2 board report as a .docx: cover page with our
 letterhead, an auto table of contents, Heading 1 sections for
 Summary / Financials / Outlook, a revenue table, footnotes on
 the figures, and 'Page X of Y' in the footer."
```

You can also point it at an existing file: *"In contract.docx, replace every 'Acme Inc.' with 'Acme LLC' using tracked changes and add a comment on clause 4."*

## Tips & gotchas

- The TOC populates only after Word opens the file and refreshes fields. If it looks empty, that's expected — press Ctrl/Cmd+A then F9, or trust that the dirty flag triggers a prompt on open.
- TOC entries come from *heading styles*, not bold text. Ask for real headings or the TOC stays blank.
- Embed images rather than linking so the file stays portable; very large images inflate the package — resize first.
- Footers with `NUMPAGES` are also field-based, so "Y" in "Page X of Y" resolves on open.

## FAQ

**Can it edit a document I already have instead of starting fresh?**
Yes — it reads the existing `.docx`, applies find-and-replace, image swaps, footnotes, or comments, and preserves the original styles.

**Does it produce PDFs?**
No. This skill outputs `.docx`. Convert to PDF afterward in Word or with a separate PDF tool.

**Will tracked changes show up as real Word revisions?**
Yes. Redline edits are written as native insertions/deletions, so reviewers see them in Word's Review pane and can accept or reject each one.