docx

name	docx
description	Create, inspect, edit, extract text from, convert, and render Microsoft Word DOCX documents while preserving formatting and validating OOXML safely. Use for .docx authoring, reading, structured edits, templates or letterheads, tables, images, headers, footers, fields, DOCX-to-text, DOCX-to-PDF, and page-rendering-for-review requests. Do not use for PDF-native, spreadsheet, or presentation work.
license	Apache-2.0
compatibility	Requires Python 3.11+ and the packages declared in requirements.txt. LibreOffice and the optional pypdfium2 package are needed only for PDF conversion and page rendering.
metadata	{"author":"Kolega","version":"1.1"}

DOCX

Use the bundled deterministic CLI. Treat sources as untrusted and immutable unless overwrite is explicitly authorized.

Workspace discipline

Work directly in visible workspace paths. Never create or use .build or another hidden build/work directory. Write requested deliverables directly to their declared destinations; if intermediate files are necessary, keep them in visible, narrowly scoped paths rather than staging the task in a hidden subtree.

Route the task

• Use this skill for DOCX creation, inspection, bounded editing, text extraction, DOCX-to-PDF conversion, and page rendering for visual review. Route PDF-native work to pdf, spreadsheets to xlsx, and presentations to pptx.
• For creation, read design intake and templates, then the create contract. Use a supplied or approved template for branded or publication-ready output. Otherwise build a deliberate baseline with section and styles; do not accept the library defaults as polished design.
• For existing documents, inspect first using inspection, then use edit operations. A placeholder template is content to fill with bounded replacement/insertion, not a blank base to append after.
• For fields, headers, footers, sections, tables, or images, jump to content blocks, headers and footers, or edit operations.
• For conversion and release, use conversion and apply the one authoritative quality contract according to the requested delivery profile.
• Before advanced or fidelity-sensitive work, read limitations. Activation preserves formatting best-effort; route signed documents, tracked-change resolution, revision-heavy editing, and fidelity-critical mutation to a native Microsoft Word workflow.
• Use examples by task for executable jobs.

Core workflow

1. Resolve the skill root and select Python 3.11+. Follow environment setup; never install without first stating what, where, and with which installer.
2. Capture the design intake and delivery profile. Preflight any template before authoring.
3. Inspect before editing. Review warnings, ordered blocks, styles, sections, stories, fields, tables, images, fonts, revisions, comments, and unsupported parts.
4. Prefer template inheritance and named styles over direct formatting. Use only the public CLI schemas in operations.
5. Keep edits explicit and bounded. Write to a distinct destination unless overwrite was explicitly authorized.
6. Reinspect the output and run the profile-dependent checks in quality. Resolve every font warning: a RELEASE BLOCKER blocks release until the font is replaced, embedded, or the user explicitly accepts the named substitution risk.
7. Render and look. Whenever layout, pagination, print, or PDF matters, run render (see render), open the produced PNG pages with the Read tool, and examine every changed page plus page 1 for text overflow or truncation, clipped or overlapping content, missing images, broken tables, and header/footer and page-number rendering. Inspect-only PDF metrics are not visual review; never claim visual correctness from JSON output alone. If rendering is unavailable, report "structural checks only; visual QA not performed." Announce before installing the optional pypdfium2 package.
8. Report warnings, renderer assumptions, field-refresh status, and preservation uncertainty. Never promise perfect round-trip fidelity.

Safety rules

• Do not bypass OOXML preflight, ZIP/resource limits, signature checks, external-relationship policy, or post-write reopen validation.
• Never use sudo pip, an interpreter under sudo for pip, or --break-system-packages; do not add skill dependencies to the host project's dependency metadata.
• Reject macro-enabled, encrypted, malformed, or oversized packages. Reject external relationships by default; explicit opt-in permits processing but is not a network sandbox.
• Supply expected replacement counts. Do not flatten text across hyperlinks, fields, drawings, comments, revisions, or unsupported markup.
• Page, TOC, reference, sequence, and date fields are markup only. A layout application must refresh them; update_fields_on_open is a request, not a guarantee.
• LibreOffice's isolated profile and process-group cleanup are lifecycle controls, not network isolation.

Resources

• Operations contract
• Executable examples
• Quality contract
• Remaining limits
• Production CLI: scripts/docx_tool.py
• Environment smoke test: scripts/smoke_test.py

Finish by confirming the source was not changed without authorization, the destination reopens, requested structures are present, the applicable acceptance criteria passed, no unaccepted RELEASE BLOCKER font warning remains, rendered pages were opened and reviewed (or the structural-only disclaimer was reported), and no generated fixtures remain in the skill directory.