docx — an agent skill for Word documents, built for review rounds

A Agent Skills-format skill that gives any SKILL.md-capable AI agent (opencode, Claude Code, OpenClaw/AutoClaw, Codex, ...) general Microsoft Word .docx powers with a hard focus on review & annotation workflows: threaded 批注/comments, tracked changes/修订/redlining, md ↔ docx round-trips, and safe in-place editing that never breaks the document.

Everything runs through one deterministic, dependency-light CLI — scripts/docxkit.py (pure zipfile + lxml) — plus the system pandoc. The agent orchestrates; it never hand-edits raw OOXML. Untouched zip parts are preserved byte-for-byte, so styles, numbering, themes, embedded objects and existing comments survive every operation.

Why this design

Hands the LLM plain commands + JSON instead of raw XML (measured approach per the docx-cli bake-off), while keeping the hard-won OOXML display rules verified against real Word/WPS files (see references/ooxml-notes.md).

Requirements

tool	needed for	notes
uv	running the CLI (uv run --with lxml ...)	or any python3 with lxml installed
pandoc ≥ 3.7	md ↔ docx conversion, reading comments/tracked changes as spans	the docx writer's native comment/ins/del span support is what makes the md track work
LibreOffice soffice (optional)	verify --soffice open-smoke-test, PDF rendering for visual checks

Install

Drop the docx/ folder (the one containing SKILL.md) into your agent's skills directory:

agent	path
opencode	~/.config/opencode/skills/docx/ or project .opencode/skills/docx/
Claude Code	~/.claude/skills/docx/
OpenClaw / AutoClaw	~/.openclaw/skills/docx/
cross-harness	~/.agents/skills/docx/

From git:

git clone https://github.com/DavidHinton-xcpc/docx-skill.git /tmp/docx-skill
cp -r /tmp/docx-skill ~/.claude/skills/docx

Restart the agent after installing (skills load at startup).

⚠️ Name collision: Anthropic's official docx skill uses the same trigger space. If both are installed, rename this folder and the name: in its SKILL.md frontmatter to docx-review.

Self-check

uv run --with lxml scripts/docxkit.py --version   # -> docxkit 2.0.0
uv run --with lxml scripts/docxkit.py inspect some.docx

Quickstart

K="uv run --with lxml path/to/scripts/docxkit.py"

# read a docx WITH comments and tracked changes, as markdown
pandoc paper.docx -t markdown --track-changes=all -o work.md

# structured read (ids, threads, anchors, highlights)
$K inspect paper.docx > threads.json

# annotate a human-authored contract in place (JSONL ops, dry-run first)
echo '{"op":"comment","anchor":{"find":"limitation of liability"},"text":"Cap is too low.","author":"Legal"}' > jobs.jsonl
$K apply contract.docx --jobs jobs.jsonl --dry-run
$K apply contract.docx --jobs jobs.jsonl -o contract-annotated.docx

# md as source of truth: build a docx whose spans become real comments/threads/revisions
$K render draft.md -o draft.docx --threads threads.json

# version round: v1.md -> v2.md as tracked changes; accept yields exactly v2
$K render v2.md -o v2.docx --baseline v1.md
$K accept v2.docx -o v2-clean.docx

# verify before handing back
$K verify contract-annotated.docx --original contract.docx --soffice

The full command/job reference lives in SKILL.md; scenario guides (papers, contracts, highlight-driven reading) in references/.

Credits / prior art (ideas referenced, no code copied)

• Anthropic's official docx skill — task/approach matrix, four-part comments, merge-runs rationale
• kklimuk/docx-cli — CLI-with-stable-locators + JSONL batch architecture
• ChipmunkRPA/redline-contract (MIT-0) — per-paragraph review.json dataset and the redline + risk-report double artifact

License

MIT-0 — see LICENSE.