Docs & Knowledge · anthropics/skills

docx

Name: docx
Author: anthropics/skills

Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Author anthropicsGitHub anthropics/skills ↗Stars 175386License Proprietary（skill 自带 LICENSE.txt：© 2025 Anthropic, PBC. All rights reserved. 按 Anthropic Consumer/Commercial Terms of Service 授权并附 ADDITIONAL RESTRICTIONS；非开源许可）Commit 41bbe19d1a

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Treat .docx as a 'ZIP container + OOXML' and adopt three distinct technical routes based on task type: programmatically generate via npm docx-js for creation; perform surgical unzip → XML edit → zip operations for editing existing files; and use pandoc for reading.

skills/docx/SKILL.md

A `.docx` is a ZIP archive of XML files. Choose your approach by task:

Route selection table: '| **Create** a new document | Write a `docx` (npm) script — see gotchas below |', '| **Edit** an existing document | `unzip` → edit `word/document.xml` → `zip` (docx-js cannot open existing files) |'. Because docx-js cannot open existing files, editing must drop down to the XML layer.

The creation side embeds a comprehensive set of anti-footgun gotchas (default A4 page, dual-width table constraints, ShadingType.CLEAR, list numbering, ImageRun type, PageBreak placement, PositionalTab dot leaders, etc.), hardcoding rendering differences between Word and Google Docs into explicit rules.

skills/docx/SKILL.md

**Table shading:** use `ShadingType.CLEAR`, never `SOLID` (renders black).

These represent a pitfalls catalog between the docx-js API and real-world renderers (Word/Google Docs/LibreOffice); e.g., 'Column widths must sum to the table width', 'Never use `\n` — use separate `Paragraph` elements.'

On the editing side, runs are normalized before text modification: Word fractures sentences into numerous `<w:r>` runs, and merge_runs.py merges adjacent identically-formatted runs to ensure reliable XML-level find-and-replace.

skills/docx/SKILL.md

Word splits text across many `<w:r>` runs (revision ids, spell-check markers), so a phrase you can see in the document often doesn't exist as a contiguous string in the XML. `merge_runs.py` merges adjacent identically-formatted runs in `word/document.xml` without changing content or rendering

The merge_runs.py docstring explains the same mechanism: 'This coalesces adjacent runs whose formatting (<w:rPr>) is identical, strips rsid attributes and proofErr markers'.

Validation loop utilizes a dual-track strategy of 'Render to images for inspection + XSD validation': soffice converts to PDF → pdftoppm produces images → the model reads images for visual QA; validate.py checks schema, relationship, and tracked change consistency.

skills/docx/SKILL.md

python scripts/office/validate.py out.docx --original doc.docx # XSD checks; --auto-repair fixes common issues

Visual QA workflow: 'python scripts/office/soffice.py --headless --convert-to pdf output.docx' → 'pdftoppm -jpeg -r 100 output.pdf page' → 'ls page-*.jpg # then Read the images'. soffice.py acts as a sandbox adaptation wrapper (falling back to an LD_PRELOAD shim when AF_UNIX is disabled).

Tracked changes (redlines) feature a dedicated acceptance tool: validate.py's --author mode verifies that all modifications are wrapped in `<w:ins>`/`<w:del>`, preventing accidental invisible edits.

skills/docx/SKILL.md

it reports any text you changed without a `<w:ins>`/`<w:del>` around it, which is easy to do by accident and invisible in the accepted view

The text also details redline semantics: 'Inside `<w:del>`, the text element is `<w:delText>`, not `<w:t>`.', the semantic meaning that deleting a paragraph mark merges into the next paragraph, and behavior differences between accept_changes.py (LibreOffice tracked changes acceptance) and pandoc.

Comments are assembled across a six-file link: comment.py automatically writes 4 comments XML files + relationships + content-type overrides, then outputs the anchor snippet to insert into document.xml.

skills/docx/SKILL.md

The script writes `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, `commentsExtensible.xml`, the relationships, and the content-type overrides.

Templates reside in scripts/templates/ (comments*.xml ×4 + people.xml); comment.py supports both unpacked directory mode and direct .docx modification (-o output).

Maintains explicit defensive measures against untrusted external .docx files: deletes symlink entries after unzipping to mitigate zip-slip style attack surfaces.

skills/docx/SKILL.md

find unpacked -type l -delete # strip symlink entries — docx from external parties is untrusted

This is a prompt-level guideline (instructing the host to prune symlinks after unzipping) rather than script enforcement; combined with XSD validation and the 'never pretty-print when editing' rule, it forms safe document surgery practices.

2Core Capabilities

01Programmatically create professional Word documents (TOC, heading hierarchy, page numbering, letterheads, tables, dot leader tabs)

02Edit and reorganize existing .docx/.dotx files (unpack → XML edit → repack), including find-and-replace

03Content reading and extraction (pandoc → markdown), with legacy .doc pre-converted to .docx via soffice

04Tracked changes: redline authoring, --author verification, and one-click acceptance via accept_changes.py

05Comment assembly (six-file linkage + anchor snippet output)

06Dual-track validation via XSD checks + rendered visual QA (--original baselining / --auto-repair)

3External Dependencies

Kind	Dependency / Endpoint
package	docx（npm，docx-js）
cli	pandoc（读取 .docx → markdown）
cli	LibreOffice soffice（渲染 QA/接受修订/.doc 转换；经 soffice.py 包装）
cli	pdftoppm（Poppler，PDF 渲染成图）
cli	unzip / zip（解包与回封 OOXML 容器）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: merge_runs.py / comment.py / accept_changes.py / validate.py / soffice.py
本地工作目录: File I/O and artifact output: output/intermediate .docx (unzip directory, zip repackaging, out.docx)

Audit Notes: Runs embedded Python scripts and local CLIs (pandoc, soffice, pdftoppm, unzip, zip) to read and write files within the local workspace. No outbound network calls (conditional npm/pip fallbacks to official registries occur only if require/import fails) and no credential reading. Considerations: ① Under restricted sandboxes, soffice.py compiles a local socket shim on the fly using gcc (self-contained, used solely for local AF_UNIX fallback, non-malicious); ② Editing external .docx files treats input as untrusted, relying on prompt-level defense (deleting symlinks + XSD validation); ③ Direct XML modifications may corrupt documents if escaping is improper. None of these pose network or credential risks.

5Second-Pass Verification

[ok] 『创建走 docx-js』路线与依赖声明 — approach 表与 Dependencies 节一致；npm 包不在仓库内（外部依赖，条件安装）。
[ok] merge_runs 机制（runs 拆分问题） — SKILL.md 描述与 merge_runs.py docstring 相互印证，均原文在。
[ok] redline --author 验收与 accept_changes — 两工具及用法命令行均存在于 SKILL.md，accept_changes.py 存在且 docstring 相符。
[ok] 批注六文件机制与 templates — comment.py 写 4 个 comments xml + rels + content-type（代码 rels/ct 常量可查）；templates/ 5 个 xml 模板（含 people.xml）与脚本引用一致。
[ok] soffice.py 沙箱 shim 无外联 — C shim 仅拦 AF_UNIX socket/listen/accept 做 socketpair 回退；编译产物在 tempdir；无任何网络地址。
[ok] 网络/凭证零命中 — 脚本层无网络调用无 env/token 读取（get_soffice_env 仅拷贝环境变量+设 SAL_USE_VCLPLUGIN/LD_PRELOAD）。
[ok] 功能声明 vs 实现（夸大检查） — description 声称的能力均有对应命令/脚本；'Do NOT use for PDFs, spreadsheets…' 负面边界清晰。唯一无法源码证实的是环境预装假设。
[ok] 元数据 — 本地 HEAD==pin 41bbe19；LICENSE.txt 为 Anthropic 专有条款（© 2025 Anthropic, PBC.），与 SKILL.md frontmatter 'Proprietary' 一致。

6Verdict & Scenarios

Exposes Word's hidden complexity: run fragmentation, six-file comment structures, tracked change semantics, and rendering quirks are turned into actionable knowledge.

The edit → validate → render-to-image Read loop enables the model to autonomously verify document correctness.

Comes with built-in XSD schema validation and auto-repair, making it far more reliable than raw XML manipulation.

Security awareness against untrusted input (symlink removal and explicit 'external parties is untrusted' posture).

Shared office/ tool tree reused across docx/pptx/xlsx, providing a single source of truth and centralized maintenance.

Best for: Ideal for managed sandboxes (such as Claude Code environments pre-equipped with docx-js, pandoc, soffice, and poppler) requiring high-frequency Word document generation/editing, template population, and automated tracked changes/comment review; its validate + render QA closed-loop is particularly suited for high-trust delivery requirements.

Not for: Not suitable for scenarios requiring WYSIWYG visual editors or exploratory complex layout designs (high trial-and-error cost for table layouts); not suitable for bare environments lacking LibreOffice/poppler (where validation and .doc conversion are unavailable); not suitable for organizations with strict license compliance barring proprietary terms; not suitable for pure read-only tasks (overkill; pandoc or markitdown is sufficient).

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload docx.tar.gz

sha256: 054b66c290295197…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 41bbe19d1a.