Plan-Validate-Execute

What it kills for you: editing while still thinking, in bulk

The scope the docs pin down

That section names four situations verbatim: Batch operations, destructive changes, complex validation rules, high-stakes operations. The worked example is concrete — updating 50 PDF form fields from a spreadsheet, where without validation the model "might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly." The flow is written as five steps: analyze → create plan file → validate plan → execute → verify.

Install (two plugins; all four skills here are in the first)

# pdf / docx / xlsx / pptx — every subject of this issue
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

# skill-creator / mcp-builder and others (used in section 03)
/plugin install example-skills@anthropic-agent-skills

You do not need the plugin: these four directories drop straight into ~/.claude/skills/ or .claude/skills/, and the Python files under scripts/ are standalone runnable anyway. When not to install: if you never touch Office or PDF files, all four are pure metadata tax. The code under scripts/ is still worth reading, which is what this issue is for.

The first usage you can run today: fill a fillable PDF

skills/pdf/forms.md opens with CRITICAL: You MUST complete these steps in order. Do not skip ahead to writing code. Four commands, run from skills/pdf/:

# 1. Probe: does the form have fillable fields (the doc drops the .py here, see 04)
python scripts/check_fillable_fields.py form.pdf

# 2. Analyze: extract the real fields as JSON — field_id / page / rect / type
python scripts/extract_form_field_info.py form.pdf field_info.json

# 3. Plan: you write field_values.json; field_id must match step 2
#    [{"field_id":"last_name","description":"...","page":1,"value":"Simpson"}]

# 4. Execute: the script checks ids and value domains first, exit 1 and no output
python scripts/fill_fillable_fields.py form.pdf field_values.json out.pdf

Step 4 is the whole pattern in miniature: fill_fillable_fields.py checks your plan against field_info.json before writing a single byte, and its errors read like ERROR: Invalid value "X" for radio group field "citizenship". Valid values are: [...]. It enumerates the legal values, which is exactly the docs' implementation tip made real: make errors verbose enough for the model to fix itself.

Mechanism: turn "what I intend to do" into something set-comparable

The official directories hold two variants; don't mix them

The difference is the moment an error surfaces. Variant A costs you an enumerable list up front (the PDF's field table, a page's row boundaries); without that list the plan's keys have nothing to compare against and the pattern decays into ceremony. Variant B needs no list, and the cost is that the original has already been modified — docx covers for that with --original: python scripts/office/validate.py out.docx --original doc.docx baselines the XSD checks against the source, so errors the original already had do not read as yours, and --auto-repair fixes common issues.

Why the intermediate output must be JSON and not prose

• Keys have to be comparable. All fill_fillable_fields.py does is three set operations: is the id in the real field table, is page right, does value fall inside the enumerations (checked_value, radio_options, choice_options). No sentence of prose supports any of the three.
• The plan has to be editable in place. Verbatim: Reversible planning: Claude can iterate on the plan without touching originals. Ten revisions of the JSON, zero opens of the original.
• Errors have to name things. check_bounding_boxes.py runs only two checks — boxes that intersect, and boxes shorter than the font size — but it quotes back the description field you wrote: FAILURE: entry bounding box height (12) for `Last name entry field` is too short for the text content (font size: 14). Increase the box height or decrease the font size. It names the field and prescribes the fix. Past 20 messages it stops: Aborting further checks; fix bounding boxes and try again.

Real usage and limits: five chains, each with its commands

1. Non-fillable PDFs: even the coordinates get validated first

python scripts/extract_form_structure.py in.pdf form_structure.json  # labels/lines/checkboxes
# you write fields.json; pdf_width/pdf_height means PDF coords, image_* means pixels
python scripts/check_bounding_boxes.py fields.json                    # validate, then fill
python scripts/fill_pdf_form_with_annotations.py in.pdf fields.json out.pdf
python scripts/convert_pdf_to_images.py out.pdf verify/              # look at it last

The same directory holds create_validation_image.py, which draws entry boxes in red and label boxes in blue over the page image. forms.md never mentions it, yet it is the most direct tool there is for letting the model validate a plan with its eyes. When not to use this chain: if the PDF has real fillable fields (run check_fillable_fields.py to find out), computing coordinates by hand is self-inflicted.

2. docx redlining: normalize before you write the plan

unzip -q doc.docx -d unpacked/ && find unpacked -type l -delete
python scripts/merge_runs.py unpacked/     # coalesce runs, or text isn't contiguous in the XML
# edit unpacked/word/document.xml — do NOT reformat or pretty-print
(cd unpacked && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx --author "Reviewer"

What merge_runs.py kills is Word slicing one sentence across a pile of <w:r> elements, so a phrase you can see in the document does not exist as a contiguous string in the XML. It is a precondition of the plan: skip it and the anchor strings in your plan match nothing. --author is a neat plan check in its own right — it reports text you changed without wrapping it in <w:ins>/<w:del>, a mistake the docs describe as easy to do by accident and invisible in the accepted view. For a clean copy use accept_changes.py, though it and pandoc --track-changes=accept share one known defect (a deleted paragraph mark leaves an emptied paragraph behind), which the SKILL.md documents itself.

3. pptx: clean up only after the structure is final

In skills/pptx/scripts, the note on clean.py is one hard constraint: Run after <p:sldIdLst> is final — it deletes slides and media nothing references any more, so running it while the structure is still moving may delete what you need next. thumbnail.py is the look-first step for choosing layouts, but its second argument is mandatory: the default prefix thumbnails lets a second deck in the same directory silently overwrite the first deck's grids.

4. xlsx: the validator is mandatory, and it only proves things evaluate

recalc.py is the only validator in this issue the docs call mandatory — openpyxl writes formulas with no cached values, so until you recalculate every formula cell reads back as None to pandas. But the SKILL.md immediately hits the brake: A green recalc proves your formulas evaluate, not that they are right. An off-by-one range yields a clean, error-free file full of wrong numbers. The remedy it offers is behavioral: write two or three formulas and check the values they pull before building out the grid.

5. Turning the pattern on skills themselves

The SKILL.md of skill-creator gives two commands: python -m scripts.run_loop --eval-set <trigger-eval.json> --skill-path <skill> and python -m scripts.package_skill <path/to/skill-folder>; scripts/ also holds quick_validate.py, run_eval.py and aggregate_benchmark.py. The order it insists on is GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself — freeze the criteria into something runnable before you start judging. When not to bother: a single SKILL.md you alone use, where writing evals costs more than it returns.

6. The model will skip the validator — that is what hooks are for

Everything above depends on the model choosing to run things in order. To pin it down, move it outside the model's judgment: Claude Code hooks fire PreToolUse before a tool call and exit code 2 blocks it outright (verbatim: On events that can block, exit 2 blocks whether or not you print JSON), and the reason can be returned precisely with permissionDecision: "deny" plus permissionDecisionReason. PostToolUse cannot block — the tool already ran — and exit 2 there only hands stderr to the model as a warning. When not to use hooks: one-off tasks, or checks that need judgment. A hook is a deterministic gate, not a reviewer (see Skill 27).

Three criteria for choosing among the chains above

1. Is there an oracle that does not depend on the model's judgment? An XSD, a field table, a formula error code all are. With no oracle, do not build this: you are only having the model grade its own paper, one extra round of tokens later.
2. Can the plan's keys be set-compared against a real list? Yes (field_id, cell addresses, slideN.xml) → go variant A and validate the plan. Only "looks about right" (copy, visual balance) → go variant B or just look at the render; don't force a JSON into existence.
3. Is failure reversible? Irreversible or bulk → variant A; the docs' four situations are exactly this criterion. Single file, re-runnable, five minutes to redo → variant B suffices, which is why docx and xlsx are variant B end to end.

Costs and alternatives: four official validators, four exit-code contracts

The exit-code table, read off the source

The consequence is concrete: write python scripts/recalc.py out.xlsx && echo OK in CI or a hook and a workbook riddled with #NAME? sails through green. The xlsx SKILL.md does warn about this — errors_found exits 0, so never treat a clean exit as a clean workbook — but the identical behavior in check_bounding_boxes.py carries no documented warning at all; you only see it by reading the source. Wire either into automation and you must parse stdout, not just check $?.

Two places where copying the doc fails

Three bills to pay

• An extra round trip. analyze → plan → validate → execute → verify is five steps, which on a small task is five times the latency. The docs bound the pattern to four situations; read the other way, that means everywhere else, don't.
• A validator covers only what it was written to cover. check_bounding_boxes.py checks intersections and heights — not missing required fields, not whether a value is correct, not what a field means. A plan that passes validation can still be entirely wrong.
• The schema drifts. The plan's field names (pdf_width vs image_width, entry_bounding_box) are a private contract between validator and executor. One upstream change to an output format and your hand-written fields.json quietly stops matching, while the validator keeps saying it is fine.

What you can do instead

1. Variant B: just do it, then validate. The official docx, xlsx and pptx skills all work this way — they have no plan file at all. For re-runnable single-file work that is enough.
2. Move the gate into a hook. PreToolUse exit 2, no opportunity for the model to skip (Skill 27).
3. Use the tool's own dry run. If something upstream can do the --check for you, don't invent an intermediate format — that's one less schema to maintain.
4. Have a second instance review it. A second pair of eyes with isolated context, at the price of coordination overhead (Skill 26).
5. Just look at it. convert_pdf_to_images.py, thumbnail.py, soffice.py --convert-to pdf plus pdftoppm — all four official skills keep this route, because some things only an eye can check.