docx-typst

DOCX ↔ Typst Bridge

What this skill carries — grep references/ for any subject the names below miss: !d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"

Typst source is the thing the repo keeps. Word is the thing coauthors edit. This skill moves a document across that boundary in both directions and reconciles what comes back.

The load-bearing fact: typ → docx → typ reaches a fixed point after one pass. So the pipe's output is itself valid Typst, the canonical form can be committed, and reconciling a coauthor's returned file collapses from "read two documents side by side" to git merge-file.

   existing.docx ──canonicalize.py --from-docx──> body.typ + media/   (bootstrap, once)
                                                     │
   main.typ ──typst compile──> PDF                   │
      │                                              │
      │ #include                                     ▼
      ▼
   body.typ ──build.py──> paper.docx ──email──> coauthor edits in Word
      ▲                                                    │
      │                                                    │ sends back
      └──── reconcile.py <── merged body.typ <── returned.docx
                                                     │
                                                     └──comments.py──> comments.json

Scripts

All under ${CLAUDE_SKILL_DIR}/scripts/. Each is self-contained and prints --help.

Run them with uv run --script, not uv run python3. Four of the five declare lxml in a PEP 723 header, and uv run python3 <path> ignores that header and fails with ModuleNotFoundError: No module named 'lxml'. --script (or executing the file directly, since the shebang is uv run) reads the header and provisions the dependency.

Script	Direction	Does
`build.py`	typ → docx	Convert with `--reference-doc` styles and stamp provenance, in one step
`canonicalize.py`	docx → typ	Bootstrap an existing Word manuscript (`--from-docx`); put a body file on its fixed point; `--check` gates it; `--lint` guards the body/main split
`reconcile.py`	docx → typ	Resolve the ancestor, three-way merge a returned file against the repo source
`comments.py`	docx or Drive → JSON	Extract comments with their anchor text, resolved state, and threading
`provenance.py`	—	Read/write the stamp directly (build.py already applies it)
`expand_citations.py`	typ → typ	Freeze every computed reference — `#cite(...)` and `@label` — into the literal body the docx path needs
`make_redline.py`	docx × docx → docx	Rebuild a coauthor's untracked edits as real tracked changes, against a baseline (stdlib + LibreOffice; no PEP 723 header)

The `main.typ` / `body.typ` split

main.typ    #import / #let / #show / #set, then #include "body.typ"    ← typst compiles this
body.typ    pure markup: = headings, prose, #emph, #footnote           ← pandoc reads this

Both paths see the same prose and neither degrades the other. The split is not stylistic tidiness — see the first fact row in ${CLAUDE_PLUGIN_ROOT}/skills/docx-typst/references/facts.md.

References — read the one the task needs

Read	When
`${CLAUDE_PLUGIN_ROOT}/skills/docx-typst/references/conversion.md`	Any actual conversion: bootstrapping a Word manuscript into `body.typ`, building the `.docx`, reconciling a returned file, rebuilding untracked edits as a redline, extracting comments
`${CLAUDE_PLUGIN_ROOT}/skills/docx-typst/references/citations.md`	A manuscript whose numbers must maintain themselves — `supra note N`, `Section IV.B`, `Id.`; the `bluebook.typ` renderer, `bib_to_entries.py`, hand-authored short forms, the `entries` schema, the two-body-file split
`${CLAUDE_PLUGIN_ROOT}/skills/docx-typst/references/facts.md`	Before changing the conversion path, or when a build/round trip behaves in a way the commands do not explain — the pandoc and typst defects this skill normalizes around, and why each rule exists
`${CLAUDE_PLUGIN_ROOT}/skills/docx-typst/references/maintenance.md`	Changing this skill or its scripts: the test suite, the two tests that pin bugs, and what "verified" requires

Red Flags — STOP

Action	Why wrong	Do instead
About to point pandoc at `main.typ`	Its `#show` rules destroy heading semantics in the docx	Point it at `body.typ`
About to pass `--allow-styling` to clear a lint error	Ships a headingless Word file	Move the directives into `main.typ`
About to hand-edit the returned `.docx` and call it reconciled	The repo source still diverges; the next build overwrites the edits	Run `reconcile.py` and merge into the source
About to resolve `<<<<<<<` markers by deleting one side wholesale	Discards a coauthor's edit unreviewed	Read both sides; ask the user when the prose choice is theirs
About to commit a merge without reading `.merged.typ.diff`	The merge is a claim about someone else's edits, unverified	Read the diff, then commit
About to send a `.docx` built from an uncommitted source	Fallback 3 needs a committed blob; the ancestor is unrecoverable	Canonicalize, commit, then build
About to run `--from-docx` without `--media-dir` because the error is in the way	Every figure is dropped and the output still looks complete	Name the sidecar directory; it is one argument
About to invoke a script with `uv run python3 <path>`	The PEP 723 header is ignored and the lxml scripts die on import	`uv run --script <path>`
About to hand-fix `Officers"` in a recovered file	The converter did it, not the source; hand-fixes are re-corrupted next pass	Re-recover with current `canonicalize.py`, which restores `’`
About to name a custom citation function in the body file	pandoc dies with `Identifier not found` and no docx is produced	`#show cite:` over the built-in `#cite(<Key>)`
About to put live `#cite` in the file `reconcile.py` merges into	It can never be canonical; the merge churns on every citation	Keep the symbolic form in `body-src.typ`, generate the literal one
About to write `#cite(<a>); #cite(<b>)` in a stacked footnote	typst groups them and the `;` vanishes from the PDF	`#cite(<a>)#[;] #cite(<b>)`
About to hand-edit the generated `cite-data.typ` to fix a short form	It is regenerated, and `--diff` will report your fix as a delta forever	Fix the `.bib` or the CSL, then regenerate and diff
About to patch hayagriva to get `supra note N`	It is statically linked into typst, and note numbers are a layout property a patch cannot reach	Render citations in typst with a `#show cite:` rule
About to `typst compile` a freshly recovered body and conclude the conversion failed	Word's TOC arrives as links to bookmarks that are not labels	Delete the recovered TOC block; `#outline()` in `main.typ` replaces it

Scope

Owns typst → docx, and Bluebook citation rendering in typst — the renderer lives here rather than in bluebook because it is co-designed with expand_citations.py, which reads the <bb-out> tag it emits, and that two-file split exists only because of the docx round trip. bluebook owns the RULES; this skill owns making typst emit them.

law-review-docx and law-econ-docx own markdown → docx; different input format, no overlap — a markdown manuscript gets Bluebook from pandoc-citeproc and the bundled CSL, and needs nothing here. docx-repair fixes OOXML damage from a cloud round trip and composes cleanly before reconcile.py when a returned file is also damaged.