| name | docx-figure-sync |
| description | Replace or update embedded figures in DOCX reports while preserving placement, sizing, and nearby captions. Use this skill when a user wants a figure updated inside a Word document, wants SVG/PNG media replaced without rebuilding the whole document manually, or needs related PDF regeneration only when explicitly requested. |
| license | BSD-3-Clause (see repo LICENSE) |
DOCX Figure Sync
Overview
Use this skill for deterministic figure replacement inside existing DOCX reports.
Prefer the surrounding document layout over ad hoc copy-paste.
When to use
- Replace an embedded figure in a
.docx
- Swap a PNG for an SVG-derived render
- Keep figure placement and caption context stable
- Check whether a DOCX/PDF pair stayed structurally valid
Workflow
- Identify the target figure and its exact position in the document.
- Update the editable figure source first when one exists (
.svg, slide source, or app asset).
- Replace the embedded media in the DOCX without changing unrelated content.
- Validate DOCX integrity and openability.
- Regenerate the PDF only when the user asks or when the task requires visual verification.
Quick start
List embedded media:
python scripts/replace_docx_media.py report.docx --list
Replace one embedded image:
python scripts/replace_docx_media.py report.docx \
--media image35.png \
--replacement updated.png \
--output report.updated.docx
Guardrails
- Keep edits surgical; do not rewrite unrelated sections.
- Preserve captions and nearby keywords unless the user asks otherwise.
- If a source figure exists, update it before touching the packaged media.
- Prefer SVG as the editable source of truth when available.
References
- Read
references/workflow.md for the replacement and validation checklist.
- Use
scripts/replace_docx_media.py for deterministic package-level replacement.
