Preface¶

When using AI to write reports, memos, or contract templates, the common output is Markdown or plain text—features that are exclusive to Word, such as typesetting, headers and footers, table of contents, and revision comments, often need to be manually formatted again. Anthropic has released the docx Skill in its open-source reference repository anthropics/skills on GitHub. This is the production-grade implementation behind Claude’s “Create and Edit Files” feature, tailored for Word documents (.docx / .dotx). After importing the entire Skill directory (including the SKILL.md instruction, auxiliary scripts, and template resources) into tools that support Agent Skills like Cursor and Claude Code, the AI agent will no longer just “describe how to write a Word document”—instead, it will follow a unified workflow to create, read, edit, and validate real documents.

What is this¶

The docx Skill is an Agent Skill maintained by Anthropic, with its official directory at:
https://github.com/anthropics/skills/tree/main/skills/docx

Its YAML preamble in SKILL.md defines the trigger conditions: the Agent should enable this Skill whenever the user mentions Word documents, .docx, .dotx, or deliverables that require formatting like table of contents, heading hierarchy, page numbers, letterheads, revision comments, annotated comments, image replacement, find-and-replace, etc. Formats like PDF, spreadsheets, and Google Docs are outside its scope.

Unlike most of the Apache 2.0 licensed example Skills in the repository, the docx Skill is source-available (source code is accessible, see the LICENSE.txt in the directory for usage permissions, it is Proprietary). As stated in the README, it, together with Skills like pdf, pptx, and xlsx, powers Claude’s Create and Edit Files product feature. For developers, its value is not just “being able to write docx files”—it is also a public template for how to package scripts and multi-file resources into a complex Skill.

Core Features and Highlights¶

The docx Skill treats Word documents as “XML inside a ZIP archive” for modular processing. The official SKILL.md summarizes three main workflows in a table:

On this basis, the Skill also bundles a complete set of Python auxiliary scripts (all located under the scripts/ directory in the Skill folder, with paths resolved relative to this directory) to cover common production environment needs:
1. Layout and structure: Table of Contents (TOC) requires using the built-in HeadingLevel.*; docx-js has several “pitfalls” listed in SKILL.md for table column widths, list numbering, page breaks, image insertion, etc. (such as default A4 size, tables need double width, literal \n cannot be used for line breaks).
2. Revision and comments: Supports writing and validating tracked changes (w:ins / w:del); accept_changes.py can generate a clean copy with all revisions accepted; comment.py can write comments linked across six XML files and output the anchor snippet that needs to be inserted into document.xml.
3. Robust workflow for editing existing docx files: merge_runs.py merges text runs split by Word to facilitate find-and-replace; scripts/office/validate.py performs XSD validation and common fixes; older .doc files can first be converted to docx via LibreOffice.
4. Output acceptance check: After generation, you can use LibreOffice to convert to PDF, then use pdftoppm to generate images, allowing the Agent to visually verify the typesetting is correct.

In terms of dependencies, the official listed tools include: docx (npm, pre-installed in the environment, run npm install docx only if require fails), pandoc, LibreOffice (soffice), and pdftoppm (Poppler).

Installation and Activation¶

Agent Skills are based on the universal SKILL.md format and can be used in environments like Cursor, Claude Code, Claude.ai, and Claude API; the installation entry points vary slightly across tools, as explained below based on Anthropic’s official repository documentation.

Cursor (Project-level)¶

Place the entire docx folder into the project’s .cursor/skills/docx/ (or the user-level ~/.cursor/skills/docx/). Cursor will automatically detect it when starting the Agent; you can also manually invoke it with /docx in an Agent conversation. A common practice is to copy from the official repository:

git clone --depth 1 https://github.com/anthropics/skills.git /tmp/anthropics-skills
cp -r /tmp/anthropics-skills/skills/docx .cursor/skills/docx

Note: You must retain the complete directory structure including SKILL.md, the peer scripts/ folder, LICENSE.txt, etc., as the script paths are referenced relatively within the Skill.

Claude Code¶

In Claude Code, you can register the anthropics/skills repository as a plugin marketplace and install the document Skill collection:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

After installation, you can directly state your requirements in the conversation, for example: “Use the docx skill to turn this outline into a Word report with a table of contents”.

Claude.ai and Claude API¶

Anthropic states that most of the example Skills in the repository are already built-in and available for paid Claude.ai plans; see Using skills in Claude for how to upload custom Skills. For using pre-built or custom Skills via the API, refer to the Skills API Quickstart.

Typical Usage Examples¶

The following commands and workflows are excerpted from the official SKILL.md, with paths relative to the scripts/ directory under the Skill folder.

1. Read existing Word content

pandoc -t markdown contract.docx

2. Edit an existing docx (unzip - modify XML - rezip - validate)

unzip -q doc.docx -d unpacked/
find unpacked -type l -delete
python scripts/merge_runs.py unpacked/
# Edit unpacked/word/document.xml in-place, do not pretty-print
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx

If you are working with revision comments, you can add --author "Your Name" during validation to ensure all changes are wrapped in tracked change markers.

3. Add comments

python scripts/comment.py unpacked/ "Fees & expenses cap is too low"
python scripts/comment.py contract.docx "This cap is too low" -o annotated.docx

The script will generate the comment-related XML and print the anchor code that needs to be inserted into document.xml; comments will not be visible in the document until the anchor is placed.

4. Visual acceptance check after generation

python scripts/office/soffice.py --headless --convert-to pdf output.docx
pdftoppm -jpeg -r 100 output.pdf page

5. Prompt example for requesting an Agent in Cursor

Please use the docx skill to generate a US Letter-sized Word memo based on the attached outline,
including primary/secondary headings, automatic table of contents, and footer page numbers;
after generation, use PDF preview to check the typesetting.

The Agent will follow the instructions in the Skill to choose between using docx-js to create a new document or unzipping and editing an existing one, and call the bundled scripts for validation.

Applicable Scenarios and Notes¶

Who and what scenarios it fits¶

• Users who need AI to directly produce downloadable, collaborative .docx files instead of Markdown previews.
• Document workflows involving revision mode, comments, templates (.dotx) in legal, business, and academic writing.
• Teams that want to reference Anthropic’s production-grade Skill directory layout (instructions + scripts + validation + licensing) to build their own enterprise document Skills.

Limitations and notes¶

1. License: The docx Skill is source-available, not licensed under Apache 2.0; please read LICENSE.txt before commercial use or redistribution.
2. Environment and dependencies: LibreOffice, pandoc, Poppler, etc., need to be available in the Agent’s executable sandbox/local environment; merely copying SKILL.md without the scripts/ folder will lose most of its functionality.
3. docx-js boundaries: It can only create new documents, and cannot open and edit existing docx files; editing old files must follow the unzip/XML workflow.
4. Official disclaimer: The repository README notes that the actual behavior of Claude’s product may differ from the reference Skill, and critical tasks should be fully tested in your own environment.

Summary¶

The docx Skill turns “AI writing Word documents” from text descriptions in chats into a scriptable, verifiable, and revamped production workflow. For developers of tools like Cursor, it is both a ready-to-use document capability package and a public template for learning how to encapsulate complex domain knowledge into Agent Skills. Official directory and Claude file feature introductions:
- Skill source code: https://github.com/anthropics/skills/tree/main/skills/docx
- Claude Create Files: https://www.anthropic.com/news/create-files