Docs & Knowledge · daymade/claude-code-skills

read-docx-review

Name: read-docx-review
Author: daymade/claude-code-skills

Reads reviewed Word/WPS docx files and extracts comments and track changes into an itemized markdown reconciliation table or JSON for decision-making. Trigger scenarios: reviewing feedback on returned contracts, agreements, manuscripts, or reports; requests like "extract docx comments", "reconcile review feedback", "read track changes", or "who commented what and where"; reviewed drafts exported from WPS Cloud / Word Online; checking what was modified in drafts returned with track changes enabled. Core guarantee: revision-aware—bare `python-docx` misses revision insertions (`w:ins`) and fails to detect whole-paragraph deletions (`w:del`), whereas this skill uses an OpenXML SDK engine to capture everything without omissions. Read-only, never modifies the source file. Boundaries: docx generation/typesetting → `docx-creator` or `minimax-docx`; PDF annotations are out of scope.

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

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

The core selling point is "revision awareness": bare `python-docx` misses revision insertions (child runs wrapped in `w:ins`) and whole-paragraph deletions (paragraph marks wrapped in `w:del`). Therefore, the engine avoids `python-docx` and instead uses official OpenXML SDK csx scripts to treat ins/del/move as first-class citizens.

daymade-docs/read-docx-review/SKILL.md

python-docx 的 `paragraph.text` 走 `paragraph.runs`，runs 只取直接子 `<w:r>`、不递归 `<w:ins>` 包装——**对方用修订模式插入的所有内容都会被漏读**

Using bare lxml's `.//w:t` can read `ins`, but cannot identify whole paragraphs wrapped in `w:del` (text in `w:t` still exists for paragraphs that disappear once revisions are accepted). Both types of missed reads were encountered in real publishing review manuscripts, and the SKILL documents this decision history.

Architecture = Python orchestration wrapper + C# dotnet-script engine: `docx_bridge_client.py` reads docx files statelessly, invokes `csharp/tasks/*.csx` (`list_comments`/`list_revisions`/`extract_views`) via subprocess, and caches results in an in-memory LRU cache keyed by (path + mtime).

daymade-docs/read-docx-review/scripts/bridge_lib/docx_bridge_client.py

cmd = ["dotnet-script", str(script), "--", str(docx), *extra_args] proc = subprocess.run(cmd, capture_output=True, text=True, env=env)

The client automatically appends `~/.dotnet/tools` to PATH and includes built-in `DOTNET_ROLL_FORWARD=Major` for compatibility with newer .NET runtimes; the Python side uses purely the standard library with zero third-party dependencies.

All three csx scripts are based on `DocumentFormat.OpenXml` 3.2.0 (declared via `#r nuget`), outputting JSON/NDJSON to Python for rendering—all parsing happens on the C# side, while Python handles only orchestration.

daymade-docs/read-docx-review/scripts/csharp/tasks/list_comments.csx

#r "nuget: DocumentFormat.OpenXml, 3.2.0" using System.Text.Json; using DocumentFormat.OpenXml.Packaging;

`list_comments` reads `WordprocessingCommentsPart` (comments.xml) + `CommentsExPart` (paraId → done) + dual anchoring via `CommentRangeStart`/`CommentReference` in `document.xml` (some WPS-exported comments only have references; verified in 6 out of 96 real-world comments).

The output is a reconciliation table with a blank "Action/Resolution" column (markdown or `--json`): commenter, anchored paragraph, comment content, status, plus paragraph-by-paragraph revision changes. Anchored paragraphs are truncated to 60 characters, while `--json` provides full text.

daymade-docs/read-docx-review/SKILL.md

产出表格自带空白「处置」列——它的用途就是拿去逐条裁决。引擎提炼自作者一个真实图书出版项目的审阅工具链（2026-02 起生产验证：单文件 96 条编辑批注、整书修订处理、输入含 WPS 云文档导出件）

Output contract: comments follow document order; replies (`replyToCommentId`) are indented under root comments; explicit prompts are output when no traces are found instead of an empty table.

Empty results are designed as "loud alerts" rather than silent empty tables: when no comments or revisions are found, it outputs "This docx carries no review traces" along with two common causes (comments dropped during export / online document unexported) to prevent falsely assuming the other party had no comments.

daymade-docs/read-docx-review/SKILL.md

无批注无修订时输出一段明确提示（「这份 docx 没有携带任何审阅痕迹」＋两个常见原因），不会静默输出空表——拿到丢了批注的副本还以为对方没意见，比读错内容更危险。

The troubleshooting table also provides debugging steps (ask the other party to re-download or re-save the docx; WPS "Download as docx" is verified to retain comments and resolved statuses).

Strictly read-only discipline: does not provide features to accept/reject revisions, reply to comments, or modify and re-export the document—modifications following reconciliation should be applied to the user's master source and regenerated.

daymade-docs/read-docx-review/SKILL.md

本 skill 只读。它不提供「接受/拒绝修订」「回复批注」「改正文再导出」——对账后的改动应落在你自己的正稿源（合同草案 SSOT、书稿源文件）再重新生成

Reference `csharp-tasks-spec.md` records paragraph indexing semantics (direct child paragraphs of body, non-recursive for tables, aligned with `python-docx`) for secondary development.

2Core Capabilities

01Full docx comment extraction (author, timestamp, content, resolved status, reply threads, paragraph anchoring, with dual-anchoring compatibility for WPS exports)

02Revision-aware three-view text: accepted/rejected/display paragraph-by-paragraph + inline ins/del and whole-paragraph ins/del detection

03Dual output formats: reconciliation table (markdown) and machine-readable full data (`--json`), with anchored paragraphs configurable as truncated or full text

04Comment context extraction: `extract_views(docx, paragraph_range=(40,55))` fetches N paragraphs before and after the anchored paragraph

05Paragraph-level utility functions replacing `python-docx`: `paragraph_text`, `paragraphs_text`, `iter_paragraphs` (all revision-aware)

06Explicit prompts for empty review traces + root cause troubleshooting (prevents misjudging that the other party had no feedback)

3External Dependencies

Kind	Dependency / Endpoint
cli	dotnet-script（csx 运行时，dotnet tool install -g）
package	DocumentFormat.OpenXml 3.2.0（NuGet，csx 首跑自动 restore 需网络 10-30s）
cli	dotnet SDK（brew install dotnet，宿主需装）

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: `python extract_review.py` / bridge client (local orchestration)
网络端点: Declares external network access: runtime network access is limited strictly to NuGet package restore for `DocumentFormat.OpenXml` during the first csx execution (the SKILL explicitly notes this takes 10-30s, cached locally afterward); d
本地工作目录: File I/O and artifact output: None (reads docx in read-only mode, outputs only to stdout/terminal table or `--json` stdout)

Audit Notes: Read-only skill: performs read-only access on user docx files without writing; runs using local python/csx without reading credentials, deleting files, or exfiltrating data; the only network activity is restoring the official `DocumentFormat.OpenXml` package from nuget.org on the first csx execution (skill states 10-30s, usable offline thereafter), targeting an expected official source.

5Second-Pass Verification

[ok] 修订感知引擎（csx + OpenXML SDK） — 三个 csx 均 #r 'nuget: DocumentFormat.OpenXml, 3.2.0' 并引用 WordprocessingPackage API；list_revisions/list_comments 输出 JSON。
[ok] Python 编排壳零第三方依赖 — docx_bridge_client.py import 仅 stdlib（subprocess/json/pathlib/functools 等）；SKILL 'Python 侧纯 stdlib' 属实。
[ok] dotnet-script 调用链 + ROLL_FORWARD/PATH 处理 — _ensure_dotnet_script_on_path 追加 ~/.dotnet/tools、env.setdefault('DOTNET_ROLL_FORWARD','Major') 均在源码。
[ok] 无状态只读 + (路径,mtime) 缓存 — _cache_key 返回 (str(p), st_mtime)；lru_cache 装饰器在三个读取函数上；无写 docx 代码路径。
[ok] python-docx 漏读叙事（w:ins/w:del） — SKILL 对 python-docx runs 直子与 w:del 段落的描述与 OpenXML 结构一致（技术事实，非夸大）；reference csharp-tasks-spec 补充语义。
[ok] 批注双锚定（WPS 兼容） — list_comments.csx 头注释记录 CommentRangeStart 首选 + CommentReference 回退及 WPS 96 条中 6 条实测。
[ok] 空结果提示防假阴性 — SKILL 声明 + extract_review.py 输出契约（无批注无修订时输出提示段）。
[ok] 无网络外发（除 NuGet 首跑） — 脚本全量扫描无 requests/urllib/http/curl；SKILL 明示 NuGet restore 需网络且仅首次。

6Verdict & Scenarios

Revision awareness provides true differentiation: bypasses `python-docx` blind spots around ins/del, using the official OpenXML SDK to read three views—a level of semantic fidelity rare among batch comment reading tools.

Read-only + stateless + caching: zero side effects on the reviewer's file, allowing safe and repeated runs on returned review drafts.

Production-verified credentials (tested on 96 comments, full-book revisions, WPS exports) and recorded architectural decisions (why community libraries were avoided) offer verifiable reliability.

The loud alert design for empty results proactively prevents the most critical false negative: assuming no comments were made when they actually were.

Best for: Ideal for extracting feedback from returned reviewed copies of contracts, agreements, manuscripts, and reports (Word/WPS comments + track changes mode), particularly for publishing editors and legal professionals; the reconciliation table with an action column naturally integrates into itemized decision workflows. Requires a .NET environment and internet access on the initial run.

Not for: Not suitable for workflows requiring direct document editing or accepting/rejecting revisions (read-only); not suitable for PDF, Lark/Feishu, or Tencent Docs comments (out of scope); not suitable for offline environments lacking .NET; fine-grained comment anchoring inside table cells exceeds body-level paragraph indexing semantics.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload read-docx-review.tar.gz

sha256: 5d26333cd2cde9a9…

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 d5c4678cb5.