SKILL 14 / DOCS · DEEP DIVE

How Document Skills Avoid Corrupting Files

Unpack-edit-validate-repack · The XSD as oracle · Why deterministic steps must be scripts

2026-09-15 · BigCat

Last issue gave you the shortlist of office skills. This one opens the scripts/ directories of the docx, pptx and xlsx skills. What is actually valuable in there is not the few hundred words of prompt in SKILL.md — it is the dozen Python scripts you can lift out and run without the skill at all.

Prerequisite → Skill 13 Office Deliverable Skills Roundup (two versions of the same four)

// WHY THIS MATTERS

When a .docx refuses to open, nobody says "the model hallucinated." They just conclude your tooling does not work. Office deliverables are the easiest class in the whole skill ecosystem precisely because they have an objective oracle: the file either matches the schema or it does not, and no human judgement is involved. This issue traces how that oracle gets wired back into the loop: unzip → merge_runs → edit XML → zip -Xr → validate.py. Every step names a real script path you can take away one at a time.

// 01

What it removes: the "I edited it, is it broken?" gap

Claim: it does not remove "writing XML." Hand-editing OOXML was never the hard part. The hard part is that after you edit, nothing tells you which byte is now non-conformant — you find out when Word pops up "there is a problem with the contents."

Installing

# Claude Code: the four live in the document-skills plugin
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

# Want only the scripts, not the skill? Clone it — scripts/ stands alone
git clone https://github.com/anthropics/skills

# System dependencies, as docx/SKILL.md lists them:
# docx (npm, preinstalled) · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)

The first thing you can actually run (straight from docx/SKILL.md)

unzip -q doc.docx -d unpacked/
find unpacked -type l -delete              # strip symlinks
python scripts/merge_runs.py unpacked/     # coalesce fragmented runs first
# edit unpacked/word/document.xml by hand — do NOT reformat
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx

Not one of those six lines is decoration. find -type l -delete keeps symlinks out of the archive. merge_runs.py decides whether you can find a whole sentence in the XML at all. zip -Xr run from inside the directory matters because zipping the folder itself adds a directory level and Word rejects the result. --original gives the validator a baseline.

The three classic ways to break this: running zip -r unpacked/ from outside (extra directory level) · letting an editor "format XML" before saving (whitespace lands in w:t and the text silently changes) · skipping merge_runs.py and then concluding the sentence you searched for is not in the document.

Primary source · anthropics/skills · skills/docx/SKILL.md (source of the commands and dependency list above)

// 02

Mechanism: what works is the XSD layer, not the prompt

Claim: these skills never try to teach the model OOXML. They compress "conformant or not" into an exit code and let the model run into it and correct itself.

Where the validator lives

skills/docx/scripts/ ├── merge_runs.py coalesce fragmented runs (run before editing) ├── accept_changes.py accept all tracked changes ├── comment.py insert / reply to comments └── office/ ← one package shared by docx · pptx · xlsx ├── validate.py single entry point; the exit code is the verdict ├── soffice.py LibreOffice wrapper (convert to PDF / other formats) ├── validators/ base.py · docx.py · pptx.py · redlining.py └── schemas/ ISO-IEC29500-4_2016 · ECMA 4th edition · mce · microsoft

validate.py takes either an unpacked directory or a packed file, plus four switches: --original to baseline against the source, --auto-repair to fix in place, --author NAME to turn on redline validation, and -v. Exit codes: 0 all checks passed, 1 validation failed, 2 argument or file error. That is the signal you can drop straight into a loop.

What it actually repairs and checks

Schema validation: docx and pptx are checked part by part against the XSDs under schemas/. This is the closest machine-readable proxy for "will this file still open."
Two concrete auto-repairs: paraId / durableId values that exceed the range OOXML allows, and w:t elements carrying whitespace without xml:space="preserve". Both are high-frequency side effects of editing XML by hand.
Redline validation: pass --author and it diffs against the original, flagging every text difference that was not recorded as <w:ins> or <w:del>. "Pretending to leave a trail" finally has a checker.

Why merge_runs comes before the edit

Word splits a single sentence into a dozen <w:r> elements — spell-check state, language marks and rsids all cut in mid-phrase. So the string "the quick brown fox" does not exist contiguously in the XML, a literal search misses, and the model starts guessing at positions. That guessing is where corruption actually begins. Coalescing first kills a whole class of hallucination at the source.

xlsx is not on this line: validate.py explicitly skips xlsx and performs no schema validation on it. You think you "ran the validator" and nothing was checked — the xlsx oracle is recalc.py in the next section.

Primary source · scripts/office/validate.py · scripts/office/schemas (where the XSDs come from)

// 03

Real usage and limits: three pipelines, three unrelated oracles

Claim: docx, pptx and xlsx look like siblings and are verified in completely different ways. Miss that and you will keep "passing validation" on a format that is never validated.

docx · oracle = XSD plus redline diff

python scripts/accept_changes.py in.docx out.docx         # accept every tracked change
python scripts/comment.py unpacked/ "Numbers disagree here"  # directory mode, for XML edits
python scripts/comment.py unpacked/ "Agreed" --parent 0       # reply to comment 0
python scripts/comment.py contract.docx "One question" -o annotated.docx
python scripts/office/validate.py out.docx --original doc.docx --author "BigCat"

In directory mode comment.py prints the <w:commentRangeStart> / <w:commentRangeEnd> / <w:commentReference> snippet for you to place inside word/document.xml: the anchor point is a judgement call left to you, while the numbering and relationship bookkeeping is done by the script. That split is the whole design in miniature.

pptx · oracle = XSD plus relationships and content types

python scripts/thumbnail.py template.pptx template-thumbs   # see layouts; always pass arg 2
python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # duplicate, never by hand
# reorder / delete = edit <p:sldIdLst> in ppt/presentation.xml
python scripts/clean.py unpacked/                            # drop orphaned slides/media/rels
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)
python scripts/office/validate.py out.pptx --original deck.pptx

Two hard rules: running add_slide.py against a .pptx directly requires -o or it rewrites your input, and a template-derived deck requires --original or the template's own inherited errors will bury yours.

xlsx · oracle = recalculation, not schema

python scripts/recalc.py output.xlsx [timeout_seconds]   # default 30
# LibreOffice evaluates every formula, rewrites the file in place, returns JSON:
# status(success|errors_found) · total_formulas · total_errors · error_summary

A counter-intuitive trap: errors_found exits 0. Only a JSON body carrying an error key — meaning nothing was recalculated at all — exits non-zero. So a clean exit code is not a clean workbook; you have to read the JSON. And a green recalc only proves the formulas evaluate, never that they are right — write two or three formulas and check the values they pull before you build out the whole sheet.

Finish with the same three QA layers

# 1. File QA
python scripts/office/validate.py out.pptx --original src.pptx
# 2. Content QA: read it back, hunt placeholders
markitdown out.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert"
# 3. Visual QA: to PDF, then to images, then actually look
python scripts/office/soffice.py --headless --convert-to pdf out.pptx
pdftoppm -jpeg -r 150 out.pdf slide && ls -1 slide-*.jpg

Each layer catches something the others cannot: schema catches "will not open," grep catches "xxx / TODO / insert title here" surviving into the final file, images catch overflowing text boxes and white-on-white. Drop one and you lose that class entirely — the three do not overlap.

Primary sources · skills/pptx/SKILL.md · skills/xlsx/SKILL.md · microsoft/markitdown (pip install 'markitdown[all]'; per the GitHub repo page, 2026-09: ~184k stars, MIT)

// 04

Costs and alternatives: this pipeline is not cheap

Claim: the price is an entire stack of system dependencies. Without LibreOffice you lose the xlsx oracle and all visual QA at once — and the half that survives will let you believe you are still verifying something.

Four honest costs

Heavy dependencies. LibreOffice + pandoc + Poppler + Node is routine inside a container, far less obviously worth it on a laptop just to recalculate one workbook. And an incomplete install does not fail loudly; it degrades silently, which is worse.
openpyxl round-trips are lossy. Straight from the docs: openpyxl does currently not read all possible items in an Excel file so images and charts will be lost from existing files if they are opened and saved with the same name. (openpyxl 3.1.5, per PyPI 2024-06). xlsx/SKILL.md adds two traps from the same root: loading with data_only=True and then saving replaces every formula with a literal permanently, and an .xlsm loses its macros unless you pass keep_vba=True. This is where "not corrupting the file" most often fails — quietly.
Generator libraries cannot open existing files. dolanmiu/docx (npm install docx, docs at docx.js.org) only constructs documents; it cannot read an existing .docx. Editing via unpack is not laziness, it is the only road.
Passing validation is not being correct. XSD governs structure; it will happily approve a structurally perfect piece of nonsense. That is why the grep and the rendered images in section 03 are not optional — the real oracle has three layers, so do not keep only the cheapest one.

Four ways to not take this road at all

Just reading once → markitdown file.xlsx or pandoc -t markdown file.docx. Unpacking is for editing, not for looking.
Generating from scratch → docx (npm) for Word, gitbrent/PptxGenJS (npm install pptxgenjs; per the GitHub repo page, 2026-09: ~6.2k stars, MIT) for slides. Still run validate and visual QA afterwards — you just never touch unpacking.
You only need one table → CSV. Dragging a whole OOXML pipeline in for two columns of data is the most common over-engineering in this series.
On claude.ai or the API → the four are preinstalled as skill_id values, zero setup (see Skill 13). This pipeline is for Claude Code and self-hosted environments.

The cost in one line: what this really sells you is a boundary — deterministic operations belong to scripts, judgement belongs to the model. Draw that line wrong (let the model improvise zip flags, relationship IDs, slide numbering) and it will corrupt files anyway, only more subtly.

Going deeper · openpyxl · Tutorial (source of the lossy round-trip sentence) · skills/docx/scripts (every script named here)

// ONE-PAGE BUYING CARD

Take these three scripts even if you never install the skills: scripts/office/validate.py (exit code is the verdict; docx and pptx) · scripts/recalc.py (the only xlsx oracle) · scripts/merge_runs.py (mandatory before editing docx).

By format: docx = unzip → merge_runs.py → edit word/document.xml → zip -Xr → validate.py --original. pptx = thumbnail.py to read layouts → add_slide.py to duplicate → clean.py to drop orphans → validate.py --original. xlsx = write with openpyxl → recalc.py → read the JSON body.

Always finish with all three layers: validate.py (file) · markitdown | grep (content) · soffice.py + pdftoppm (visual). In that order.

Explicitly do not: hand-copy slide XML to duplicate a slide · zip from outside unpacked · treat recalc's exit 0 as "no errors" · omit --original on template-derived files · save a workbook you loaded with data_only=True · assume validate.py checked your xlsx.

The one-line test: is anything watching this step that can exit non-zero? If not, do not let the model perform it — make it a script, or cut it from the process.

// GLOSSARY

OOXML (Office Open XML): What docx / pptx / xlsx really are: a zip archive of XML parts plus media. Unpack-edit-repack works only because of this.
Part and [Content_Types].xml: Each XML file in the package is a part; [Content_Types].xml at the root declares what kind each one is. Together with the _rels/ relationship files it forms a ledger — adding or deleting files without updating the ledger is the most common way to corrupt a document.
Run (<w:r>): A stretch of uniformly formatted text in Word. One sentence is routinely split across a dozen runs; that is what merge_runs.py puts back together.
rsid: A marker Word attaches per editing session. It is a leading cause of fragmented runs and carries no meaning for content.
XSD (XML Schema Definition): A machine-readable description of what counts as valid XML. schemas/ ships ISO-IEC29500-4:2016 and the ECMA 4th edition, plus the mce and microsoft extension sets.
MCE (Markup Compatibility): The OOXML mechanism (mc:AlternateContent) that lets newer features degrade gracefully in older readers. It is also why validation cannot rely on a single schema set.
Redlining: Recording edits inside the document as <w:ins> / <w:del>. validate.py --author checks that every text difference actually left such a trail.
Lossy round-trip: Reading a file and writing it back while some content silently disappears — openpyxl and charts or images, for instance. It does not raise, so knowing is the only defence.

// FURTHER READING

anthropics/skills · skills/docx/SKILL.md — source of the six-line edit workflow, the tracked-changes validation and the dependency list (docx / pandoc / LibreOffice / pdftoppm)
skills/pptx/SKILL.md — arguments for thumbnail.py, add_slide.py and clean.py, plus the original wording of the file / content / visual QA trio
skills/xlsx/SKILL.md — the recalc.py JSON fields and exit-code contract, the two-pass load_workbook read, plus keep_vba, merged cells and quoting traps
scripts/office/validate.py — four switches, three exit codes, the two auto-repairs, and the fact that xlsx is skipped, all in one file
scripts/office/ — the package shared by all three skills: soffice.py, validators/ (base · docx · pptx · redlining), schemas/
scripts/office/schemas/ — ISO-IEC29500-4_2016 and ECMA 4th edition XSDs, plus mce and microsoft extensions
microsoft/markitdown — the read-back tool behind the content QA layer, pip install 'markitdown[all]'; per the GitHub repo page, 2026-09: ~184k stars, MIT
openpyxl · Tutorial — where "images and charts will be lost from existing files" comes from; version 3.1.5 per PyPI 2024-06
dolanmiu/docx — the JS library for generating Word files (docs at docx.js.org); it cannot open existing files, which is why editing must unpack
gitbrent/PptxGenJS — the JS library for generating decks, npm install pptxgenjs; per the GitHub repo page, 2026-09: ~6.2k stars, MIT
Skill 13 · Office Deliverable Skills Roundup — the two versions of the four (open-source on GitHub vs preinstalled skill_id) and ten ways to install them; the prerequisite for this issue

// THINK IT THROUGH

Why are document skills the easiest class to get right, and writing skills the hardest?

Because the former have an oracle nobody argues with: the schema passes or it does not, the file opens or it does not. Acceptance criteria for writing differ per person, so all you can do is approximate them with examples. Before making anything a skill, ask whether something can exit non-zero on it.

What is the difference between putting zip -Xr in SKILL.md as a prompt and wrapping it in a script?

The failure mode. As a prompt, the model eventually picks different flags, and the ways it can be wrong are unbounded. As a script it either runs or errors. Deterministic operations belong to code — of everything in these three skills, that is the principle applied most consistently.

Is recalc.py returning errors_found with exit 0 a bug?

No. "The workbook contains #REF!" and "recalculation itself failed" are different events: the first needs a human to look, the second needs the pipeline to stop. Collapsing them into one exit code would be the real bug. The price is that you must read the JSON body — one line of documentation traded for one class of false negative.