A .docx is a ZIP archive of XML files, and the docx skill's SKILL.md is organised around that fact: creating a document and editing one are two different routes, and only one of them can be done with the same library.
What it actually finishes
- Create a Word document from scratch — a runnable
docx(npm) script that produces headings, tables of contents, page numbers, letterheads, tables and images. - Produce a professional document — a report, memo, letter or template that has to look like a Word file rather than plain text in a
.docxwrapper. - Edit an existing file — unpack the archive, edit
word/document.xml, zip it back. This is the only route for files that already exist. - Read a document's content —
pandoc -t markdown file.docxconverts it to Markdown you can read and reason about. - Work with tracked changes and comments — reviewing and revising text that came back with someone else's edits in it.
- Insert or replace images, and run find-and-replace across a document.
When it fires, and when to skip it
The skill fires on any mention of "Word doc", "word document", .docx or .dotx, and on any request that a report, memo, letter or template be delivered as a Word file. The format requirement is the trigger — asking for a memo in Markdown is a different task.
It does not fire for PDFs, spreadsheets, Google Docs, or general coding tasks that happen to touch document text. A .docx produced as a side effect of something else is not what this skill is for; it fires when the Word file is the thing being handed over.
How to check it worked
- For a document you created, convert it back with
pandoc -t markdown output.docxand read the text. This catches the classic failure where a script runs cleanly but the paragraphs never made it into the document body. - For a document you edited, unpack the result again and confirm
word/document.xmlcontains your change — that is the file the renderer actually reads. - Open the file once in a real Word-compatible viewer to look at what plain text cannot show: the table of contents, page numbering, headers and letterhead layout.
A table of contents field is the one element that can look broken everywhere except Word itself, because the page numbers are calculated when the document is opened rather than written into the file. If the contents are right in Word, it worked.
What goes wrong
docx-js cannot open an existing file. This is the most important sentence in the whole skill. If you generate a new document with a script and then try to load the original one into it to make a change, nothing happens, or you get a fresh document without the original content. Existing files go through unpack → edit word/document.xml → zip. There is no third option.
Don't run npm install for docx. The library is already present in the skill's environment. Installing it again is how you end up with two versions and an error that looks unrelated to what you changed.
Script paths are relative to the skill's own directory. A script copied into a different working folder will not find the resources it expects.
Reading and writing are different tools. pandoc converts a document to Markdown for reading; it does not write .docx files. Creation is the docx script, editing is the unpack-and-rezip route. Mixing them up is how a "quick edit" turns into a rewritten document.
Repacking has to preserve the archive layout. When you zip an unpacked .docx back up, the parts belong at the archive root the way Word wrote them. A .docx zipped from inside a subfolder is a file that will not open.
Review metadata is content. Tracked changes and comments live in the package alongside the text, so a pass that regenerates the document from extracted text silently accepts every pending change and drops every comment. If a review round matters, edit the XML rather than rebuilding the file.
How it compares
- docx — words, layout and review state. The format that stays editable after the agent is done with it.
- xlsx — numbers and formulas, including the tables you might otherwise try to paste into Word.
- pptx — slides, when the same argument has to be presented rather than read.
- pdf — the locked-down version you send to someone. Word first, PDF last, not the other way round.
Try a sample task
This walkthrough gives you a prompt and an acceptance check to run in your own client.
Create and review a Word document
Use a short meeting brief with two section headings, a small table and a named comment target.
Use the DOCX skill to build minutes.docx from this brief. Put action items in a table and add a review comment to the deadline paragraph.
What to verify The file opens in Word or LibreOffice, the table columns fit the page, and the comment is anchored to the intended paragraph.
Best for Editable reports, review rounds, tracked changes and comments.
How to use docx
Work on a copy when editing a source document. Specify whether the deliverable should show revisions, comments, or a clean final document.
Acceptance check Open the result in Word, select All Markup, and confirm the revisions, comments and page layout are present.
Install for your agent
Run the command from your project directory. After installation, reload the client if it has already started. Tool access and execution features depend on the client.
Claude Code
npx skills add anthropics/skills --skill docx -a claude-codeCodex
npx skills add anthropics/skills --skill docx -a codexCursor
npx skills add anthropics/skills --skill docx -a cursorGitHub Copilot
npx skills add anthropics/skills --skill docx -a github-copilotAsk your agent to install the skill
Install docx from anthropics/skills in this project. Show me the destination folder and report any dependencies the source lists.
For manual installation, copy the entire skill folder, including references and scripts, into a skill directory supported by your client. See the installation guide.
What the upstream guide covers
The upstream Word guide separates document creation from editing existing Word packages. It also documents markup and comments, along with a verification step for the edited file.
HavenSkills workflow check
November 17, 2026 · Programmatic check with python-docx on a small review document.
- What we checked
- Saved and reopened a DOCX. The title retained its Heading 1 style and the table retained both headers, Owner and Next step.
- Scope
- This check covers heading and table preservation. It does not establish support for tracked changes or verify the visual layout in Word.
Requirements, permissions and limits
- Runtime
- Node.js and docx-js for creation; Python and LibreOffice for selected operations
- File and tool access
- Work on a copy of the input. Creating or editing the file can require Node.js or Python helpers, and conversion or rendering can use LibreOffice.
- Limits to check
- Font substitution and Word-versus-LibreOffice differences can change pagination and table wrapping. Check the output in the reader’s target viewer.
Frequently asked questions
Can it open a .docx I already have?
Yes, but not with the document-creation library. Existing files are edited by unpacking the archive, changing word/document.xml, and zipping it back up.
Does it support .dotx templates?
Yes — the skill's trigger list names .dotx, Word templates, alongside .docx.
Can it handle tracked changes and comments?
The skill fires on them, and they live in the package rather than in the visible text, which is why editing the XML preserves them and regenerating from extracted text does not.
How do I read a Word file without opening anything?
Run pandoc -t markdown file.docx. It gives you the text as Markdown, which is usually enough to reason about structure and content.
Is it safe for a document that matters?
The repository states that these skills are for demonstration and teaching and should be tested thoroughly before critical use. Check the output in a real viewer before sending it.