docx

Overview of docx skill

What the docx skill is for

The docx skill helps an agent create, inspect, and modify Microsoft Word .docx files with fewer blind spots than a generic prompt. It is best for users who need real DOCX workflows: generating a polished Word deliverable, extracting content for review, editing existing files, handling comments or tracked changes, or repairing package-level issues by working directly with the Office XML structure.

Who should install docx

Install this docx skill if you regularly need to:

• produce Word documents, not just plain text
• edit an existing .docx without manually clicking through Word
• preserve document structure such as headings, comments, and revisions
• convert legacy .doc files before further processing
• inspect package contents when normal text extraction is not enough

It is especially useful for AI-assisted document operations where the output must remain a usable .docx, not merely a markdown draft.

What makes docx different from a normal prompt

The main differentiator is workflow specificity. The skill does not treat DOCX as “just text.” It recognizes that a .docx is a ZIP archive of XML files and points the agent toward the right path for each job:

• pandoc for text-focused reading and extraction
• unpack/edit/repack for structural edits
• LibreOffice automation for some format conversions and accepting tracked changes
• validation and repair steps when XML edits risk breaking the file

That makes docx more credible for DOCX workflows than a generic “write a report” instruction.

Best-fit jobs to be done

Use docx when the real job is one of these:

• “Create a Word report with sections and professional formatting.”
• “Read this .docx and summarize it, including tracked changes.”
• “Replace or restructure content inside an existing Word file.”
• “Add comments or process revisions programmatically.”
• “Convert .doc to .docx so it can be edited safely.”

Important limits before you adopt

This skill is not a universal office suite. It is strongest when the task clearly targets .docx. It is a weaker fit for:

• PDFs
• Google Docs-native collaboration
• spreadsheet-heavy workflows
• visual layout perfection that requires manual Word desktop review
• users who need zero local tooling such as pandoc or LibreOffice

The practical tradeoff: docx gives more control, but package-level editing requires care.

How to Use docx skill

Start with the install context, not just a command

The repository does not advertise a single formal docx install command inside SKILL.md, so treat it as a skill you add from the Anthropic skills repository, then use with local helper scripts and external tools. In practice, users evaluating docx usage should assume they may need:

• Python
• pandoc for reading and conversion-oriented extraction
• LibreOffice soffice for .doc conversion and accepting changes
• a shell environment that can run the included Python scripts

If your environment blocks GUI-ish office tooling or native subprocess calls, check that first. That is often the real adoption blocker.

Read these files first

For fastest orientation, read in this order:

1. skills/docx/SKILL.md
2. skills/docx/scripts/office/unpack.py
3. skills/docx/scripts/office/pack.py
4. skills/docx/scripts/accept_changes.py
5. skills/docx/scripts/comment.py
6. skills/docx/scripts/office/soffice.py

This path tells you the actual operating model of the docx skill: read, unpack, edit, validate, repack, and use LibreOffice only where XML-only editing is the wrong tool.

Choose the right workflow for the task

The best docx guide starts by selecting the right lane:

• Read or analyze content: use pandoc or inspect unpacked XML
• Create a new document: use the document-generation route referenced in SKILL.md
• Edit an existing document: unpack → modify XML/assets → repack
• Convert .doc to .docx: use LibreOffice conversion first
• Accept tracked changes: use the provided LibreOffice macro helper
• Add comments: use the comment script plus correct XML markers

If you skip this decision and jump straight to editing, quality drops fast.

Inputs the docx skill needs for good output

For reliable docx usage, give the agent more than “make a Word doc.” Strong inputs usually include:

• the source file path, if editing
• the desired output file path
• whether the task is create, read, convert, annotate, or revise
• formatting requirements such as headings, page numbers, TOC, tables, letterhead
• whether tracked changes or comments must be preserved
• whether the document contains images, tables, or templates that must survive intact

A weak prompt:

• “Edit this Word document.”

A stronger prompt:

• “Open contract_review.docx, preserve tracked changes, summarize all comments, then create a new executive_summary.docx with H1/H2 headings, a short risks table, and a final recommendations section.”

Practical commands users actually care about

A few high-value operations surfaced directly in the repository:

Convert legacy .doc before anything else:

python scripts/office/soffice.py --headless --convert-to docx document.doc

Extract text while keeping revision context:

pandoc --track-changes=all document.docx -o output.md

Unpack a DOCX for XML-level edits:

python scripts/office/unpack.py document.docx unpacked/

Repack after editing:

python scripts/office/pack.py unpacked/ output.docx --original document.docx

These commands reflect the actual docx for DOCX Workflows value: not just writing text, but operating on Word packages safely.

How to prompt the agent so docx triggers correctly

The skill is more likely to activate well when your request names the file type and operation clearly. Include:

• .docx
• the desired end state
• whether the work is on an existing file or from scratch
• what must be preserved

Good trigger examples:

• “Create a polished .docx board memo from these notes.”
• “Read this .docx and extract text including tracked changes.”
• “Unpack and update the title page, then repack the .docx.”
• “Add review comments to specific paragraphs in this Word document.”

Avoid vague phrasing like “make a document better” if you actually need package-safe editing.

When to use pandoc versus unpacking XML

This is one of the biggest practical decisions.

Use pandoc when you want:

• readable text extraction
• markdown conversion
• easier review of tracked changes
• content analysis more than layout surgery

Use unpack/edit/repack when you need:

• comments
• tracked-change-aware structural edits
• image or package part replacement
• low-level fixes inside word/ XML and relationships

If your goal is semantic reading, XML editing is overkill. If your goal is exact DOCX mutation, plain text extraction is not enough.

Special handling for tracked changes and comments

The repository includes unusually practical support here:

• scripts/accept_changes.py accepts tracked changes using LibreOffice
• scripts/comment.py helps insert comments into unpacked documents
• helper code in scripts/office/helpers/ addresses run merging and redline simplification

This matters because revisions make raw DOCX XML much messier. If your documents involve legal review, editorial comments, or negotiated drafts, the docx skill is more compelling than a basic document generator.

Watch for XML-specific quality traps

Some failure modes are easy to miss:

• comment markers must be placed correctly in document.xml
• text for comments should be XML-escaped
• DOCX edits can break relationships or schema validity
• run fragmentation can make search/replace unreliable
• tracked changes can distort the apparent text flow

The included pack/validate path reduces risk, but it does not remove the need for careful task framing.

Environment details that can block adoption

A practical blocker in docx install decisions is office automation. The repository’s soffice.py includes logic for sandboxed environments where Unix sockets may fail and an LD_PRELOAD shim may be needed. That is a strong signal that the authors expect real environment friction.

If your deployment cannot run LibreOffice, some workflows still work, but:

• .doc conversion becomes harder
• accepting tracked changes via the provided script is not available
• some “just automate Word-like behavior” requests may need a different toolchain

Suggested workflow for consistent results

A good default docx guide workflow is:

1. Confirm whether the source is .doc or .docx.
2. Convert .doc to .docx first if needed.
3. Decide whether the task is text extraction or package editing.
4. Unpack only when structure-level edits are required.
5. Make targeted changes, not broad regex-style XML rewrites.
6. Repack with validation against the original when possible.
7. Open the output in Word or LibreOffice for final visual smoke testing.

That workflow prevents the most common corruption and mismatch issues.

docx skill FAQ

Is docx good for beginners?

Yes, if your need is clear and limited, such as converting, extracting, or making small edits. But advanced docx usage quickly becomes package-level XML work. Beginners can use it successfully if they stay within a guided workflow and do not treat Word files like plain text blobs.

When is docx better than an ordinary writing prompt?

Use docx when the output must be an actual Word file or when you must preserve structure from an existing .docx. A normal writing prompt can draft content, but it usually does not tell the agent how to convert, unpack, validate, or handle comments and revisions safely.

Can the docx skill create new documents from scratch?

Yes, but the repository’s strongest evidence is around practical file operations and editing workflows, not just prose generation. If your main need is “write content,” many tools can do that. If your need is “deliver or edit a usable .docx,” this skill is a better fit.

Does docx work for old .doc files?

Indirectly. Legacy .doc files should be converted first using LibreOffice. That is an important boundary: the docx skill is for .docx workflows, not native .doc editing.

Is docx suitable for legal or review-heavy documents?

Potentially yes, because tracked changes, comments, and validation are first-class concerns in the repository. That said, review-heavy documents should always be opened after generation to confirm visible behavior in Word-compatible editors.

When should I not use docx?

Skip this docx skill if:

• you only need plain text output
• the destination is PDF rather than Word
• the workflow is Google Docs-first
• you cannot run the local tools it depends on
• pixel-perfect desktop publishing matters more than editable DOCX structure

How to Improve docx skill

Give docx explicit output constraints

The fastest way to improve docx results is to specify the finished artifact, not just the topic. Include:

• target filename
• source filename
• preserve vs rewrite instructions
• required sections
• style constraints
• whether comments, revisions, images, or tables must remain intact

This reduces tool-choice mistakes and prevents the agent from defaulting to a text-only path.

Ask for a workflow choice before execution

For better docx usage, prompt the agent to state which path it will use:

• pandoc
• unpack/edit/repack
• LibreOffice conversion
• comment or revision tooling

Example:

• “Before editing, tell me whether this task should use pandoc extraction or unpack/repack, and why.”

That simple step catches many wrong-turn decisions early.

Improve search and replace tasks with structure hints

If you need replacements, identify where the content lives:

• body text
• headers/footers
• comments
• tables
• title page
• specific section headings

Why this helps: DOCX text is often split across many runs. A vague “replace all mentions” request can miss matches or break formatting.

Be careful with comments and XML escaping

When adding comments, provide clean, XML-safe text. The repository explicitly notes that comment text should be pre-escaped. If your comment includes ampersands, smart quotes, or special symbols, mention that they must be escaped or normalized.

This is a small detail, but it materially affects whether the resulting file opens cleanly.

Use original-file validation whenever possible

When repacking, include --original if you have the source file. That gives the validator more context and makes the docx skill safer for edits to existing documents. It is one of the highest-value habits in this skill’s workflow.

Iterate after first output with file-aware feedback

Do not stop at “looks wrong.” Better follow-up feedback is:

• “The document opens, but comments do not appear in Word.”
• “Tracked changes were flattened; preserve them instead.”
• “The body text updated, but header branding stayed old.”
• “The XML packed, but formatting broke in the table section.”

That kind of feedback helps the agent choose the next repair step instead of retrying blindly.

Common failure modes to catch early

Watch for these before scaling up a workflow:

• output opens but comments are missing
• tracked changes are unintentionally accepted or lost
• edits affect only visible text, not headers/footers
• smart quotes or symbols break XML
• repacked files pass zipping but fail in Word

A quick smoke test on a small document is worth it before processing a large batch.

How to get better results on complex docx files

For complex docx for DOCX Workflows, split the task:

1. extract and inspect
2. decide edit points
3. apply one class of change at a time
4. repack and validate
5. visually verify

This is slower than a one-shot prompt, but much more reliable for templates, contracts, reports, and revision-heavy files.

What to improve if you extend the docx skill

If you are evaluating how to improve the docx skill itself, the most valuable additions would be:

• clearer documented entrypoints for common tasks
• example prompts mapped to each workflow lane
• a tighter install/prerequisites checklist
• more explicit guidance on creating new documents versus editing existing ones
• end-to-end examples for comments, redlines, and image replacement

Those improvements would reduce adoption friction more than adding generic prose.