docx-ru

---
name: docx-ru
description: Read and create .docx files on Windows with proper UTF-8 / Cyrillic support. Lightweight alternative to anthropic-skills:docx without pandoc / LibreOffice dependencies. Use when a .docx file is involved - extracting text or building a document with paragraphs, lists and tables. (Чтение и создание .docx с поддержкой русского.)
---

# DOCX (Windows + Cyrillic)

Two CLI scripts on top of Python (read) and `docx-js` (write). Works on Windows, doesn't crash on cp1251, doesn't require pandoc / soffice.

## When to use

- The user attached a `.docx` file and wants its content extracted
- Need to generate a letter / commercial offer / spec / report as `.docx`
- Need to save your work as a real Word document, not markdown

For tracked changes, comments, or find-and-replace inside existing documents - use the official `anthropic-skills:docx` instead.

## Reading

```bash
python "<SKILL_DIR>/scripts/read_docx.py" "/absolute/path/to/file.docx"
```

Where `<SKILL_DIR>` is typically:
- Linux / macOS: `~/.claude/skills/docx-ru`
- Windows: `%USERPROFILE%\.claude\skills\docx-ru`

Output is plain text split by paragraphs (UTF-8 stdout). Add `--tables` to render tables as pipe-separated rows: `cell | cell | cell`.

## Creating

1. Write a JSON config with blocks (see schema below) using the `Write` tool. A typical scratch path is `./_tmp_docx.json`.
2. Run the builder:

```bash
node "<SKILL_DIR>/scripts/build_docx.js" --config "./_tmp_docx.json" --out "./result.docx"
```

The script automatically replaces em-dashes and en-dashes with regular hyphens so generated text doesn't look AI-written. Pass `--keep-dashes` to disable.

## JSON config schema

```json
{
  "font": "Arial",
  "fontSize": 22,
  "pageSize": "A4",
  "margins": 1134,
  "blocks": [
    { "type": "h1", "text": "Heading 1" },
    { "type": "h2", "text": "Heading 2" },
    { "type": "p",  "text": "Regular paragraph", "bold": false, "italic": false, "center": false },
    { "type": "pRich", "runs": [
        { "text": "Bold fragment: ", "bold": true },
        { "text": "and the rest in plain text." }
      ]
    },
    { "type": "bullet", "text": "Bulleted list item" },
    { "type": "number", "text": "Numbered list item" },
    { "type": "divider" },
    { "type": "image", "path": "./logo.png", "width": 300, "center": true },
    { "type": "table",
      "widths": [3600, 2700, 2700],
      "header": ["Column 1", "Column 2", "Column 3"],
      "rows": [
        ["cell", "cell", "cell"]
      ],
      "firstColBold": true,
      "shadeHeader": "E8E8E8"
    }
  ]
}
```

All fields except `blocks` are optional. Defaults: Arial 11pt, A4, 2 cm margins, tables with grey header and thin grey border. Column widths are in DXA (1440 = 1 inch, 1134 = 2 cm). The table width is the sum of `widths`.

For `image` blocks: `path` is required, `width`/`height` are in pixels (if only one is given, the other scales proportionally from the file's natural size; if neither, natural size is used). Supported formats: PNG, JPG, GIF, BMP — type is detected by extension and magic bytes. `center` aligns the image; `before`/`after` set paragraph spacing in twips.

A complete example is in `examples/basic.json` next to this file.

## Dependencies

Must be installed globally on the user's machine (skill assumes they exist):

- Node.js + `npm i -g docx` (tested with `docx@9.6.1`)
- Python 3 with built-in `zipfile`

## Working rules

- For a new `.docx`, **always** use this skill instead of writing an inline JS-script with `docx-js` boilerplate from scratch
- For reading an existing `.docx`, try `read_docx.py` first; only escalate to `anthropic-skills:docx` if you actually need tracked changes / complex formatting
- In Windows paths, use double backslashes inside JSON (`"C:\\Users\\..."`) or forward slashes
- After creating a `.docx`, verify file size with `ls -l`; a normal document is > 8 KB

---

## По-русски

Облегчённый skill для чтения и создания `.docx` на Windows с нормальной поддержкой русского. Альтернатива `anthropic-skills:docx`, когда не нужны tracked changes / find-replace.

**Чтение:** `python <SKILL_DIR>/scripts/read_docx.py file.docx [--tables]` - выдаёт plain text с разбивкой по параграфам, опционально рендерит таблицы. UTF-8 stdout всегда (на cp1251 не падает).

**Создание:** написать JSON-конфиг (схема выше) → `node <SKILL_DIR>/scripts/build_docx.js --config spec.json --out result.docx`. Автоматически заменяет em-dash и en-dash на обычный дефис, чтобы текст не выглядел сгенерированным ИИ. `--keep-dashes` отключает.