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

> Avoid common pitfalls when creating document skills. Learn to validate Office Open XML, fix front-matter errors, and ensure relationship consistency for successful skill development.

- Repository: [Anthropic/skills](https://github.com/anthropics/skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py) to generate new skill scaffolds and [`skills/skill-creator/scripts/package_skill.py`](https://github.com/anthropics/skills/blob/main/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)【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`](https://github.com/anthropics/skills/blob/main/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:

```bash
python scripts/office/validate.py mydoc.docx

```

The validator entry point in [`skills/docx/scripts/office/validate.py`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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:

```javascript
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`](https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/validators/redlining.py) prints a helpful error when [`document.xml`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/helpers/simplify_redlines.py)).
- Run the redline validator after any edit:

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

```

To accept all tracked changes programmatically, use:

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

```

*Reference*: The [`accept_changes.py`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/unpack.py) → edit XML → **must** call [`pack.py`](https://github.com/anthropics/skills/blob/main/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)【https://github.com/anthropics/skills/blob/main/skills/docx/scripts/office/pack.py#L9-L14】.

Complete workflow example:

```bash

# 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`](https://github.com/anthropics/skills/blob/main/fontTable.xml) entry or absent font files |

**Fix**: Add assets to the package using the helpers in [`helpers/simplify_redlines.py`](https://github.com/anthropics/skills/blob/main/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)【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)【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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/SKILL.md) and verify they are installed in the execution environment.

## Summary

- **Validate front-matter strictly**: Include only `name` and `description` in [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) to avoid packaging failures.
- **Always run schema validation**: Use [`scripts/office/validate.py`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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.