docx

Files (59)

• LICENSE.txt
• SKILL.md
• dml-chart.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• dml-chartDrawing.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• dml-diagram.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• dml-lockedCanvas.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• dml-main.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• dml-picture.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• dml-spreadsheetDrawing.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• dml-wordprocessingDrawing.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• pml.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-additionalCharacteristics.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-bibliography.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-commonSimpleTypes.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-customXmlDataProperties.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-customXmlSchemaProperties.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-documentPropertiesCustom.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-documentPropertiesExtended.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-documentPropertiesVariantTypes.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-math.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• shared-relationshipReference.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• sml.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• vml-main.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• vml-officeDrawing.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• vml-presentationDrawing.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• vml-spreadsheetDrawing.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• vml-wordprocessingDrawing.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• wml.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• xml.xsd · ooxml/schemas/ISO-IEC29500-4_2016/
• opc-contentTypes.xsd · ooxml/schemas/ecma/fouth-edition/
• opc-coreProperties.xsd · ooxml/schemas/ecma/fouth-edition/
• opc-digSig.xsd · ooxml/schemas/ecma/fouth-edition/
• opc-relationships.xsd · ooxml/schemas/ecma/fouth-edition/
• mc.xsd · ooxml/schemas/mce/
• wml-2010.xsd · ooxml/schemas/microsoft/
• wml-2012.xsd · ooxml/schemas/microsoft/
• wml-2018.xsd · ooxml/schemas/microsoft/
• wml-cex-2018.xsd · ooxml/schemas/microsoft/
• wml-cid-2016.xsd · ooxml/schemas/microsoft/
• wml-sdtdatahash-2020.xsd · ooxml/schemas/microsoft/
• wml-symex-2015.xsd · ooxml/schemas/microsoft/
• pack.py · ooxml/scripts/
• unpack.py · ooxml/scripts/
• validate.py · ooxml/scripts/
• __init__.py · ooxml/scripts/validation/
• base.py · ooxml/scripts/validation/
• docx.py · ooxml/scripts/validation/
• pptx.py · ooxml/scripts/validation/
• redlining.py · ooxml/scripts/validation/
• docx-js.md · references/
• ooxml.md · references/
• __init__.py · scripts/
• document.py · scripts/
• comments.xml · scripts/templates/
• commentsExtended.xml · scripts/templates/
• commentsExtensible.xml · scripts/templates/
• commentsIds.xml · scripts/templates/
• people.xml · scripts/templates/
• utilities.py · scripts/

SKILL.md (first lines)

# DOCX creation, editing, and analysis

## Overview

A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

## Workflow Decision Tree

### Reading/Analyzing Content
Use "Text extraction" or "Raw XML access" sections below

### Creating New Document
Use "Creating a new Word document" workflow

### Editing Existing Document
- **Your own document + simple changes**
  Use "Basic OOXML editing" workflow

- **Someone else's document**
  Use **"Redlining workflow"** (recommended default)

- **Legal, academic, business, or government docs**
  Use **"Redlining workflow"** (required)

## Reading and analyzing content

### Text extraction
If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:

```bash
# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all
```

### Raw XML access
You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.

#### Unpacking a file
`python ooxml/scripts/unpack.py <office_file> <output_directory>`

#### Key file structures
* `word/document.xml` - Main document contents
* `word/comments.xml` - Comments referenced in document.xml
* `word/media/` - Embedded images and media files
* Tracked changes use `<w:ins>` (insertions) and `<w:del>` (deletions) tags

## Creating a new Word document

When creating a new Word document from scratch, use **docx-js**, which allows you to create Word documents using JavaScript/TypeScript.

### Workflow
1. **MANDATORY - READ ENTIRE FILE**: Read [`references/docx-js.md`](references/docx-js.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
3. Export as .docx using Packer.toBuffer()

## Editing an existing Word document

When editing an existing Word document, use the **Document library** (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.

### Workflow
1. **MANDATORY - READ ENTIRE FILE**: Read [`references/ooxml.md`](references/ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for the Document library API and XML patterns for directly editing document files.
2. Unpack the document: `python ooxml/scripts/unpack.py <office_file> <output_directory>`
3. Create and run a Python script using the Document library (see "Document Library" section in references/ooxml.md)
4. Pack the final document: `python ooxml/scripts/pack.py <input_directory> <office_file>`

The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.

## Redlining workflow for document review

This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. **CRITICAL**: For complete tracked changes, you must implement ALL changes systematically.

**Batching Strategy**: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.

**Principle: Minimal, Precise Edits**
When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the `<w:r>` element from the original and reusing it.

Example - Changing "30 days" to "60 days" in a sentence:
```python
# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'
```

### Tracked changes workflow

1. **Get markdown representation**: Convert document to markdown with tracked changes preserved:
   ```bash
   pandoc --track-changes=all path-to-file.docx -o current.md
   ```

2. **Identify and group changes**: Review the document and identify ALL changes needed, organizing them into logical batches:

   **Location methods** (for finding changes in XML):
   - Section/heading numbers (e.g., "Section 3.2", "Article IV")
   - Paragraph identifiers if numbered
   - Grep patterns with unique surrounding text
   - Document structure (e.g., "first paragraph", "signature block")
   - **DO NOT use markdown line numbers** - they don't map to XML structure

   **Batch organization** (group 3-10 related changes per batch):
   - By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
   - By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
   - By complexity: Start with simple text replacements, then tackle complex structural changes
   - Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"

3. **Read documentation and unpack**:
   - **MANDATORY - READ ENTIRE FILE**: Read [`references/ooxml.md`](references/ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
   - **Unpack the document**: `python ooxml/scripts/unpack.py <file.docx> <dir>`
   - **Note the suggested RSID**: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.

4. **Implement changes in batches**: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:
   - Makes debugging easier (smaller batch = easier to isolate errors)
   - Allows incremental progress
   - Maintains efficiency (batch size of 3-10 changes works well)

   **Suggested batch groupings:**
   - By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")

From vadimcomanescu/codex-skills, MIT.

More from vadimcomanescu/codex-skills