word-document — Claude Code skill: .docx work via MCP

---
name: word-document
version: "2.0"
last_updated: 2026-09-08
tags: [docs, document, writing, quality, templates]
description: "Word (.docx) manipulation via MCP server. Use for reading, creating, editing, formatting Word documents including tables, footnotes, comments, images, headers, styles, and PDF conversion."
---
# Word Document Workflows

> Tech Stack Target / Version: Word desktop or `python-docx` automation with current OOXML-compatible workflows.

Use this skill when `.docx` layout and document structure matter, not just the raw text.

- Leverage native parallel subagent dispatch and 200k+ context windows where available.


## Current MCP Reality

Microsoft publicly documents a Word MCP server in the Microsoft 365 Agents Toolkit preview, but tool availability still depends on the host. In GitHub Copilot you may see Word-specific tools; in other clients they may be missing. If direct Word MCP access is unavailable, use the included local script workflow.

## Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

- Creating or editing `.docx` reports, memos, or structured deliverables
- Applying headings, tables, images, or styles
- Reviewing or extracting document structure
- Preparing Word output before a later PDF conversion

## Practical Workflow

1. Confirm whether the client exposes Word MCP capabilities.
2. Start with structure: title, headings, sections, tables.
3. Apply styling consistently only after the structure is right.
4. Validate comments, footnotes, and references before export.
5. Use the local generator script when MCP access is unavailable.

## MCP Fallback – Native Automation

When MCP is unavailable, use native automation: `python-docx` for `.docx`, direct OOXML inspection for unsupported structures, and PDF export checks when layout matters. Preserve styles, tables, headers, footers, comments, tracked-change expectations, and metadata, then reopen or parse the document before claiming success.

<!-- MCP:START -->

<!-- PORTABILITY:START -->
## Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
  workflow in project instructions when folder discovery is unavailable.
- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
- Codex: install or sync the folder into
  `$CODEX_HOME/skills/word-document` and restart Codex after major changes.

<!-- PORTABILITY:END -->

## MCP Availability And Fallback

Preferred MCP Server: Word Document MCP

- Fallback prompt: "Use the Word Document Workflows skill without MCP. Follow the documented local or manual fallback, show the selected tool surface, and report the verification evidence."
- Use `python-docx`, Word desktop, or document export scripts when the MCP surface is unavailable.
- Re-open or render the document locally so formatting, comments, and pagination are verified before delivery.
- Do not claim an MCP operation was used when the active host does not expose it.

<!-- MCP:END -->

## Anti-Patterns

- Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
- Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
- Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.

## Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Word Document artifact type, target format, and required output fidelity are stated before editing.
2. Pass/fail: MCP availability is checked and the native automation fallback path is named when MCP is absent.
3. Pass/fail: The produced file or formula is opened, parsed, rendered, or otherwise validated locally.
4. Pressure-test scenario: Apply the workflow to a file with formatting, metadata, or conversion edge cases and verify nothing important is lost.
5. Success metric: Zero unverified document claims; the artifact itself is the evidence.

## Document Checklist

- [ ] Heading hierarchy is clear
- [ ] Tables are readable and consistently styled
- [ ] Comments or review notes are intentional
- [ ] Placeholder text is removed
- [ ] The final document was re-opened or otherwise verified after generation

## References & Resources

### Documentation
- [DOCX Formatting Reference](./references/docx-formatting-reference.md) - Practical formatting notes and document structure guidance

### Scripts
- [DOC Template Generator](./scripts/doc-template-generator.py) - Local fallback for generating Word-ready document structures

### Examples
- [Report Generation Example](./examples/report-generation-example.md) - Example report workflow for `.docx` output

## Related Skills

- [documentation-authoring](../documentation-authoring/SKILL.md): Use it when the workflow also needs drafting structured technical or product documents.
- [documentation-patterns](../documentation-patterns/SKILL.md): Use it when the workflow also needs reusable documentation structures and templates.
- [documentation-quality](../documentation-quality/SKILL.md): Use it when the workflow also needs documentation review standards and quality gates.
- [documentation-verification](../documentation-verification/SKILL.md): Use it when the workflow also needs final documentation validation before publishing.