# DOCX

Read, inspect, edit, or create Microsoft Word `.docx` documents, including structured...

- Repository: https://github.com/TokenRhythm/opensquilla (7104 stars)
- Category: Documents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add TokenRhythm/opensquilla --skill docx -g -a claude-code -y`
Codex: `npx skills add TokenRhythm/opensquilla --skill docx -g -a codex -y`
Cursor: `npx skills add TokenRhythm/opensquilla --skill docx -g -a cursor -y`
Gemini CLI: `npx skills add TokenRhythm/opensquilla --skill docx -g -a gemini-cli -y`

## Description

Read, inspect, edit, or create Microsoft Word `.docx` documents, including structured text extraction, style-preserving edits, tracked-change review, and generation from a brief.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# docx

Work with Microsoft Word `.docx` files. The format is OOXML, a zip container
holding XML parts (`word/document.xml`, `styles.xml`, `numbering.xml`, headers,
footers, relationships). Treat structure as primary; rendered text is a view.

## Decide the path first

Pick **one** path up front. The right path depends only on what is on disk
before you start.

| You have | Goal | Path |
|---|---|---|
| Existing `.docx` | Read text/structure | A. Inspect |
| Existing `.docx` | Modify content while keeping styles | B. Edit-in-place |
| Nothing or a brief | Build a new doc | C. Create from scratch |

If the user hands you a doc and asks for changes, default to path B and treat
the input as the visual style baseline. Only choose path C when the user says
"start fresh" or there is no input.

---

## Path A: Inspect

Dump structure as JSON for inspection without mutating anything.

```bash
python {baseDir}/scripts/inspect_docx.py /path/to/doc.docx
```

Output schema:

```json
{
  "paragraphs": [{"index": 0, "text": "...", "style": "Heading 1"}, ...],
  "tables": [[["row0,col0", "row0,col1"], ...], ...],
  "sections": 1,
  "has_tracked_changes": false
}
```

Use this whenever you need to see what is in the doc before deciding how to
edit. The output is stable and machine-readable, diff two inspect outputs to
verify a round-trip preserved everything you intended.

---

## Path B: Edit in place

Two sub-strategies; pick by how invasive the edit is.

### B1. Run-level text replacement (preferred)

When the change is "swap this string" or "fill these placeholders": mutate
runs in place. This preserves all theme/style/font settings.

```bash
python {baseDir}/scripts/edit_docx.py input.docx ops.json --out output.docx
```

`ops.json` is a list of operations:

```json
[
  {"op": "replace_run", "para": 0, "run": 0, "text": "Q3 Review"},
  {"op": "replace_text", "find": "{{CLIENT}}", "with": "Acme Corp"}
]
```

The rest: https://github.com/TokenRhythm/opensquilla/blob/HEAD/src/opensquilla/skills/bundled/docx/SKILL.md