docx-ru — Claude Code skill for .docx on Windows + Cyrillic

A lightweight Claude Code skill for reading and creating .docx files that works correctly on Windows with Cyrillic text and other non-ASCII content.

Built as an alternative to the official anthropic-skills:docx when you don't need tracked changes / find-replace and just want a fast way to read or generate Word documents from Claude Code without pandoc / LibreOffice.

Why this exists

• The official skill depends on pandoc and soffice, which are not always installed on Windows.
• Its validator script crashes on Windows because the default stdout codec (cp1251) cannot encode the → character it tries to print.
• Reading Cyrillic content via the default extractor often produces UnicodeEncodeError unless stdout is manually wrapped.
• For most everyday tasks (commercial offers, technical specs, letters, reports) you don't need tracked changes — you just want paragraphs, headings, lists and tables out the door.

This skill solves all of the above with two small CLI scripts:

• scripts/read_docx.py — extracts text and tables, always UTF-8 stdout
• scripts/build_docx.js — builds a .docx from a JSON spec using the global docx package

It also automatically replaces em-dashes (—) and en-dashes (–) with regular hyphens (-) in generated documents, since em-dashes have become a tell-tale sign of AI-generated text. Pass --keep-dashes to disable.

Install

1. Clone into your Claude Code skills directory

Windows:

git clone https://github.com/KondrashovDenis/claude-md-docx-skill.git "%USERPROFILE%\.claude\skills\docx-ru"

macOS / Linux:

git clone https://github.com/KondrashovDenis/claude-md-docx-skill.git ~/.claude/skills/docx-ru

2. Install the global docx package

npm install -g docx

(Tested with docx@9.6.1. Python 3 with zipfile is also required — it ships with the standard library.)

3. (Optional) Allow the scripts in your settings.json to skip permission prompts

Add to ~/.claude/settings.json (or %USERPROFILE%\.claude\settings.json on Windows):

{
  "permissions": {
    "allow": [
      "Bash(node *docx-ru*)",
      "Bash(python *docx-ru*)"
    ]
  }
}

Usage

Once installed, Claude Code will auto-discover the skill. You can either let Claude trigger it automatically when you mention a .docx file, or invoke the scripts directly.

Reading a .docx

python "$HOME/.claude/skills/docx-ru/scripts/read_docx.py" path/to/file.docx

Add --tables to render tables as pipe-separated rows (Header 1 | Header 2 | Header 3).

Creating a .docx

1. Write a JSON spec (see examples/basic.json for a full example):

{
  "blocks": [
    { "type": "h1", "text": "Hello, world!" },
    { "type": "p",  "text": "This is a paragraph." },
    { "type": "bullet", "text": "First list item" },
    { "type": "bullet", "text": "Second list item" },
    { "type": "table",
      "widths": [3000, 3000, 3000],
      "header": ["Column 1", "Column 2", "Column 3"],
      "rows": [["a", "b", "c"]]
    }
  ]
}

2. Run the builder:

node "$HOME/.claude/skills/docx-ru/scripts/build_docx.js" \
  --config spec.json \
  --out output.docx

JSON spec reference

Top-level (all optional except blocks):

Key	Default	Description
font	"Arial"	Default document font
fontSize	22	Default size in half-points (22 = 11pt)
pageSize	"A4"	"A4" or "Letter"
margins	1134	Page margin in DXA (1134 = 2 cm, 1440 = 1 inch)
blocks	(required)	Array of block objects

Block types:

Type	Required fields	Optional fields
h1, h2, h3	text
p	text	bold, italic, center, before, after
pRich	runs[] (each with text, optional bold/italic)	before, after, center
bullet	text
number	text
divider	(none)
image	path	width, height (px; one scales the other proportionally, omit both for natural size), center, before, after
table	widths[], rows[][]	header[], firstColBold, shadeHeader (hex without #)

Images: supported formats are PNG, JPG, GIF, BMP. Type is detected from the file extension (falling back to magic-byte sniffing). Natural dimensions are read directly from the file header, so you don't need a separate image library.

Table column widths are in DXA (1440 = 1 inch). Their sum becomes the table width.

Builder flags

Flag	Effect
--config <path>	(required) JSON spec file
--out <path>	(required) Output .docx path
--keep-dashes	Don't replace em/en-dashes with hyphens

What this skill does NOT do

For tracked changes, comments, find-and-replace inside existing documents or footnotes — use the official anthropic-skills:docx instead. This skill is intentionally minimal.

Contributing

PRs welcome. Things that would be great to add (in rough priority order):

• Numbered lists with custom start values and nested levels
• Headers and footers
• Page breaks ({ "type": "pageBreak" })
• Two-column / multi-column layouts
• Custom heading styles via top-level styles config
• Hyperlinks ({ "type": "p", "runs": [{ "text": "...", "link": "https://..." }] })

License

MIT — see LICENSE.

Author

Created by Denis Kondrashov with Claude Code.