Microsoft Word agent skill

TL;DR: microsoft-word is a free, MIT-licensed agent skill that teaches AI agents (Claude Code, Cursor, Codex, Gemini CLI and other agents that read SKILL.md skills) to read, create, edit, convert, update and safely share Word documents, with tested guidance for python-docx, docx.js, docxtpl, pandoc, mammoth, LibreOffice, Office.js, VBA and Microsoft Graph. Install: npx skills add skillsaas/microsoft-word or npm install microsoft-word.

microsoft-word is an Agent Skills skill that teaches AI coding agents (Claude Code, Cursor, Codex, Gemini CLI and others) to read, create, edit, convert, update and safely share Word documents without breaking them.

Unofficial. Microsoft and Word are trademarks of Microsoft Corporation. This project is not affiliated with or endorsed by Microsoft.

Use it when

• Find and replace in a .docx "does nothing" because Word split the text across runs.
• Creating or editing .docx with python-docx, docx.js (docx on npm), docxtpl or pandoc and the result loses formatting.
• A TOC, page numbers or cross-references are stale, or you need a PDF without Word.
• Reading documents with tracked changes, comments, content controls, headers and footers or footnotes.
• Accepting changes, removing comments, hidden text and metadata before a document leaves the company.
• Handling untrusted documents: macros (.docm), remote templates, DDE and INCLUDE fields, altChunk, OLE.
• Converting .doc, .rtf, .dotx, .odt and comparing two versions.
• Automating Word with Office.js, VBA, COM or Microsoft Graph.

Install

npx skills add skillsaas/microsoft-word     # skills CLI, reads SKILL.md at the repo root
npm install microsoft-word                  # files land in node_modules/microsoft-word/
# Planned, not yet published: npx @skillsaas/cli add microsoft-word --claude

Works today: copy SKILL.md, references/ and scripts/ into your agent's skills folder, for example ~/.claude/skills/microsoft-word/, and keep the folder name. SKILL.md calls scripts as python <skill-dir>/scripts/NAME.py, so they work from any working directory.

Script dependencies: Python 3.9+ and pip install -r scripts/requirements.txt (lxml). docx_refresh.py also needs LibreOffice (tested 25.2.3.2 only; older versions unverified) and, on Linux, bubblewrap (bwrap, preferred) or working user namespaces (unshare). It refuses on macOS and Windows; references/fallbacks.md says what to do there. python-docx is not needed by the scripts.

Third-party tools are not bundled; the scripts import lxml and call the others if installed. Their licenses: lxml BSD-3-Clause, python-docx MIT, mammoth BSD-2-Clause, pandoc GPL-2.0-or-later, LibreOffice MPL-2.0, bubblewrap LGPL-2.0-or-later, docxtpl LGPL-2.1, docx (npm) MIT, msoffcrypto-tool MIT, openpyxl MIT. skill.json lists them under third_party_licenses. lxml installs from wheels on common platforms; building from source needs libxml2-dev and libxslt1-dev.

Quick setup on Debian or Ubuntu:

pip install -r scripts/requirements.txt
sudo apt install libreoffice-writer bubblewrap   # only for docx_refresh.py
python scripts/docx_refresh.py --check            # JSON: what can run here

skill.json holds the name, version, description and entry file for catalogs.

What it does

• inspect_docx.py: read-only inventory with --json, risks (macros, remote templates, DDE and INCLUDE fields, altChunk, OLE), residue and --check-clean.
• docx_replace.py: find and replace across split runs, optional tracked replacement, --expect count, never overwrites.
• docx_sanitize.py: accept changes, remove comments, hidden text and metadata, then re-inspect and fail on anything left.
• docx_refresh.py: rebuild the TOC and fields or export PDF with LibreOffice in bubblewrap (or unshare), no network, macros off (Linux).
• References for OOXML, extraction losses, conversion fidelity, Office.js, VBA, COM and Graph; Python 3.9+ with lxml.

FAQ

What is the microsoft-word skill? An Agent Skills package (a SKILL.md plus references and Python scripts) that tells an AI agent how to work with Word documents correctly. It is unofficial and not affiliated with Microsoft.

Why does find and replace in a .docx miss text? Word often splits one word across several runs with different formatting. docx_replace.py replaces across runs and reports how many matches it changed.

How do I update a table of contents without Word? docx_refresh.py updates fields and the TOC with LibreOffice in a sandbox on Linux; it refuses on macOS and Windows, and references/fallbacks.md lists the options there.

How do I remove tracked changes, comments and metadata before sharing? docx_sanitize.py makes a cleaned copy and re-inspects it; inspect_docx.py --check-clean shows what remains.

How do I install it in Claude Code? npx skills add skillsaas/microsoft-word, or copy SKILL.md, references/ and scripts/ to ~/.claude/skills/microsoft-word/, then pip install -r scripts/requirements.txt.

Is it safe with documents from strangers? The inspector only reads and lists macros, remote templates and fields. LibreOffice runs only in isolation with no network and macros off.

Contents

| Path | Purpose | | :--- | :--- | | SKILL.md | Short router: decision guide, workflow, security rules, must-know traps, script usage, verification checklist | | references/troubleshooting.md | Symptom, check and fix table | | references/extraction.md | Text extraction: python-docx vs pandoc vs mammoth, tested losses, recipes | | references/fallbacks.md | What to do when lxml, LibreOffice, bwrap, unshare or Word is missing; legacy .doc | | references/ooxml.md | Parts, runs, styles, numbering, sections, headers and footers, fields, content controls, tracked changes, comments, repair | | references/libraries.md | Tool choice table, all tested traps, writing patterns, python-docx, docx.js, docxtpl, lxml | | references/conversion.md | LibreOffice and pandoc fidelity, formats, fonts and layout | | references/automation.md | Office.js Word API, VBA, COM, Microsoft Graph, SharePoint and Word for the web | | references/recipes.md | Four worked examples, then replace, templates, mail merge, compare, TOC, headers, tables, images, accessibility, sections | | references/security.md | Macros, remote templates, DDE, external links, altChunk, isolation, redaction | | scripts/inspect_docx.py | Read-only inventory with --json, risks, residue and --check-clean | | scripts/docx_replace.py | Find and replace across split runs, optional tracked replacement, --expect, never overwrites | | scripts/docx_sanitize.py | Accept changes, remove comments, hidden text, glossary, metadata (thumbnail, rsids, docVars, customXml) and active content; re-inspects and fails on any remaining risk | | scripts/docx_refresh.py | LibreOffice in bubblewrap (or unshare) with no network, no user files and macros off: rebuild TOC, update fields, export PDF/DOCX/ODT | | scripts/wordpkg.py | Shared hardened package reader and no-overwrite writer |

Tests: python tests/smoke_test.py (repo only, not in the npm package). It builds fixtures, prints PASS, FAIL and SKIP lines and a summary, and skips LibreOffice checks where soffice or unshare is missing. 151 checks in 0.1.4.

Discovery metadata

• Skill name microsoft-word: same as the folder, the GitHub repo skillsaas/microsoft-word and the npm package microsoft-word.
• Formats: docx, docm, dotx, dotm, doc, rtf, odt; PDF output.
• Tested with python-docx 1.2.0, mammoth 1.11.0, pandoc 3.9, LibreOffice 25.2.3.2, lxml 6.1, Python 3.13 (docx 9.10.0 and docxtpl 0.20.2 in 0.1.0).
• Catalog of all skillsaas skills (planned, not yet published): https://github.com/skillsaas/index
• GitHub topics: agent-skill, agent-skills, skill-md, claude-code-skill, microsoft-word, docx, python-docx and more.
• docx_refresh.py --sandboxed is for operators only; agents never pass it (references/security.md).

License

MIT