Common Pitfalls When Creating Document Skills: A Complete Guide to Office Open XML Validation

The most common pitfalls when creating document skills include malformed front-matter in SKILL.md, missing Office Open XML schema validation, broken relationship consistency in document packages, and improper handling of tracked changes metadata.

Document-oriented skills in the anthropics/skills repository manipulate complex Office Open XML packages. Understanding the interaction between skill descriptors, validation scripts, and document internals prevents the most frequent errors that cause packaging failures or corrupted output.

1. Incomplete or Incorrect Front-Matter in SKILL.md

The skill descriptor (SKILL.md) must contain only the required front-matter fields: name and description. Adding extra keys or stray markup confuses the validator and the skill-packager, causing packaging failures.

According to the docx skill definition in skills/docx/SKILL.md, the required schema appears at the top of the file【https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md#L1-L4】. To ensure compliance, use skills/skill-creator/scripts/init_skill.py to generate new skill scaffolds and skills/skill-creator/scripts/package_skill.py to validate front-matter before bundling.

2. Missing Schema Validation for Office Open XML

A generated .docx file is a zip archive of XML files. If any XML deviates from the Office 2006-2016 schemas, LibreOffice or Word will reject the file or silently corrupt it.

Common symptoms and causes include:

Symptom	Typical Cause
"Document appears corrupted"	Duplicate or missing relationship IDs (<Relationship Id="rIdX"...>) in skills/docx/scripts/office/validators/base.py【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/base.py#L73-L77】
"Images not displayed"	Unreferenced media files left in the package【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/base.py#L61-L66】
"Tracked changes lost"	Redline validator not run after editing—redline metadata lives in word/comments.xml and must be preserved【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/redlining.py#L13-L72】

Always run the schema validator after any modification:

python scripts/office/validate.py mydoc.docx

The validator entry point in skills/docx/scripts/office/validate.py orchestrates these checks【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validate.py#L9-L35】.

3. Ignoring Relationship Consistency

Office files maintain a network of relationship files (_rels/*.rels). The validator in skills/docx/scripts/office/validators/base.py checks two critical aspects:

1. Broken references – a part points to a missing target.
2. Duplicate relationship IDs – IDs must be globally unique.

Both conditions trigger a CRITICAL error that will corrupt the document【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/base.py#L71-L76】.

Pitfall: Manually editing XML and forgetting to update the corresponding .rels entry.

Fix: Use the validate_all_relationship_ids method (invoked by validate.py) to catch these before repacking.

4. Page Size Mismatches

docx-js defaults to A4 paper size, but many U.S. users expect Letter. If the size is not set explicitly, printed PDFs or converted images will be the wrong dimensions, leading to layout glitches.

The docx creation guide in skills/docx/SKILL.md highlights this default【https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md#L78-L81】.

Fix: Add a SectionProperties block with the desired size when constructing the document:

const { Document, Packer, Paragraph, TextRun } = require('docx');
const fs = require('fs');

const doc = new Document({
    sections: [{
        properties: {
            // Explicitly set US Letter size to avoid A4 default
            pageSize: { width: 12240, height: 15840 } // 8.5" x 11"
        },
        children: [
            new Paragraph({
                children: [
                    new TextRun("Hello, world!"),
                ],
            }),
        ],
    }],
});

Packer.toBuffer(doc).then(buffer => {
    fs.writeFileSync("hello.docx", buffer);
});

5. Improper Handling of Tracked Changes

Tracked changes are stored as <w:ins> / <w:del> elements plus comment ranges. If a skill modifies the main document XML without preserving the author attribute or without reconciling w:commentRangeStart / w:commentRangeEnd, the resulting file can become unreadable by Word.

The redlining validator in skills/docx/scripts/office/validators/redlining.py prints a helpful error when document.xml is missing or malformed【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/redlining.py#L69-L73】.

Fix:

• Use the infer_author helper to preserve the original author name (helpers/simplify_redlines.py).
• Run the redline validator after any edit:

python scripts/office/validate.py edited.docx --original original.docx

To accept all tracked changes programmatically, use:

python scripts/accept_changes.py input.docx output.docx

Reference: The accept_changes.py script description【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/accept_changes.py#L1-L5】.

6. Forgetting to Re-Pack After Unpacking

The typical workflow involves unpacking, editing, and repacking: unpack.py → edit XML → must call pack.py to rebuild the zip. Skipping this step leaves the user with a folder of XML files instead of a usable .docx.

The pack script’s usage is documented in skills/docx/scripts/office/pack.py【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/pack.py#L9-L14】.

Complete workflow example:

# Unpack the original document

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

# ... edit XML files in unpacked/ ...

# Re-pack the modified files

python scripts/office/pack.py unpacked/ edited.docx --original original.docx

# Run the full validator (schema + relationships + redlines)

python scripts/office/validate.py edited.docx --original original.docx

7. Overlooking Asset Limitations

Document skills often embed binary assets (images, fonts). Common issues include disappearing images or unapplied fonts.

Issue	Cause
Images disappear after repack	Asset not listed in _rels or missing from media/ folder
Fonts not applied	Missing fontTable.xml entry or absent font files

Fix: Add assets to the package using the helpers in helpers/simplify_redlines.py or manually update the relationship files to ensure every binary part is referenced in the corresponding .rels file.

8. Unclear Skill Triggers in Descriptions

The description field drives the skill’s activation. If it does not list the key trigger phrases (e.g., "Word doc", ".docx", "letterhead"), the skill may never be selected, even though it works perfectly.

The docx description lists a comprehensive set of triggers in skills/docx/SKILL.md【https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md#L2-L4】.

9. Missing License or Proprietary Tag

If a skill’s license line is omitted or mismatched with the actual LICENSE file, packaging scripts will raise an error. The docx skill includes its license line in skills/docx/SKILL.md【https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md#L4-L5】.

10. Ignoring Platform-Specific Dependencies

Some scripts rely on external binaries (pandoc, LibreOffice, pdftoppm). Running them on a system without these tools leads to runtime failures.

The README sections for conversions in skills/docx/SKILL.md show the required commands【https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md#L21-L44】.

Fix: Document the dependencies in the skill’s README or SKILL.md and verify they are installed in the execution environment.

Summary

• Validate front-matter strictly: Include only name and description in SKILL.md to avoid packaging failures.
• Always run schema validation: Use scripts/office/validate.py to catch broken relationships, duplicate IDs, and malformed XML before distribution.
• Preserve relationship consistency: Every XML part must have valid entries in _rels/*.rels files; manual edits must sync these references.
• Set explicit page sizes: Default A4 dimensions in docx-js cause layout issues for Letter-size documents unless overridden in SectionProperties.
• Handle tracked changes carefully: Preserve author attributes and comment ranges when editing document.xml, and validate redlines against originals.
• Maintain asset references: Images and fonts must be listed in relationship files and stored in correct media folders to prevent disappearing content.
• Check platform dependencies: Ensure pandoc, LibreOffice, or other external binaries are installed before running conversion scripts.

Frequently Asked Questions

What causes "Document appears corrupted" errors in generated docx files?

This error typically stems from duplicate or missing relationship IDs in the _rels/*.rels files. According to skills/docx/scripts/office/validators/base.py, both broken references and duplicate relationship IDs trigger CRITICAL errors that corrupt the document【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/base.py#L71-L76】. Always run validate.py after editing to catch these issues before repacking.

Why do images disappear after I repack a docx file?

Images disappear when binary assets are not properly referenced in the relationship files or are missing from the media/ folder. The validator in skills/docx/scripts/office/validators/base.py checks for unreferenced media files that can cause display failures【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/base.py#L61-L66】. Ensure every image has a corresponding entry in the .rels file and is stored in the correct media directory.

How do I preserve tracked changes when editing document XML?

Tracked changes are stored as <w:ins> and <w:del> elements with associated comment ranges. When modifying document.xml, you must preserve the author attribute and reconcile w:commentRangeStart and w:commentRangeEnd tags. The redlining validator in skills/docx/scripts/office/validators/redlining.py will flag malformed tracked changes【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/redlining.py#L69-L73】. Use the infer_author helper and validate against the original document to ensure integrity.

What external dependencies are required for document skills?

Document skills often require platform-specific binaries such as pandoc for markdown conversion, LibreOffice for accepting tracked changes, and pdftoppm for image extraction. The skills/docx/SKILL.md file documents these requirements in the conversion sections【https://github.com/anthropics/skills/blob/main/skills/docx/SKILL.md#L21-L44】. Verify these dependencies are installed in your execution environment before running conversion or validation scripts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}