/document-creator

name: document-creator
description: Create and edit professional Word (.docx) and Excel (.xlsx) documents. Use to create reports, memos, proposals, financial models, invoices, or modify existing Office documents. Supports rich text, tables, lists, images, formulas, charts, and tracked changes.

Document Creator

Create professional-grade Word and Excel documents for expert knowledge workers.

Quick Reference

| Task | Tool | Command Pattern | |------|------|-----------------| | Create Word doc | `docx_create.ts` | `bun run scripts/docx_create.ts --spec spec.json --output doc.docx` | | Edit Word doc | `docx_unpack.py` + XML editing + `docx_pack.py` | See Word Editing section | | Create/Edit Excel | `xlsx_create.py` | `uvx --with openpyxl python scripts/xlsx_create.py --spec spec.json --output file.xlsx` | | Verify formulas | `xlsx_recalc.py` | `uvx --with openpyxl python scripts/xlsx_recalc.py file.xlsx` |

Decision Tree

What type of document?
├── Word (.docx)
│   ├── Create new → Use docx_create.ts (TypeScript)
│   └── Edit existing → Unpack → Edit XML → Repack (Python)
└── Excel (.xlsx)
    └── Create or Edit → Use xlsx_create.py (Python)

Word Document Creation

Use `scripts/docx_create.ts` to create new Word documents from a JSON specification.

Running the Script

# From the scripts directory
cd ~/.pipali/skills/document-creator/scripts
bun run docx_create.ts --spec spec.json --output report.docx

# Or with full path
bun run ~/.pipali/skills/document-creator/scripts/docx_create.ts \
  --spec spec.json \
  --output report.docx

Specification Format

{
  "properties": {
    "title": "Document Title",
    "creator": "Author Name"
  },
  "styles": {
    "defaultFont": "Calibri",
    "headingFont": "Cambria",
    "fontSize": 11
  },
  "sections": [
    {
      "properties": { "type": "continuous" },
      "children": [
        { "type": "heading", "level": 1, "text": "Main Title" },
        { "type": "paragraph", "text": "Introduction paragraph." },
        { "type": "heading", "level": 2, "text": "Section 1" },
        { "type": "bulletList", "items": ["First point", "Second point"] },
        { "type": "numberedList", "items": ["Step 1", "Step 2"] },
        {
          "type": "table",
          "headers": ["Column A", "Column B"],
          "rows": [
            ["Cell 1", "Cell 2"],
            ["Cell 3", "Cell 4"]
          ]
        },
        { "type": "image", "path": "/path/to/image.png", "width": 400 },
        { "type": "pageBreak" }
      ]
    }
  ]
}

Element Types

| Type | Required Fields | Optional Fields | |------|-----------------|-----------------| | `heading` | `level` (1-6), `text` | `style` | | `paragraph` | `text` (string or RichText) | `bold`, `italic`, `alignment`, `color` | | `bulletList` | `items` (array of string or RichText) | `level` | | `numberedList` | `items` (array of string or RichText) | `level` | | `table` | `headers`, `rows` | `widths`, `headerStyle` | | `image` | `path` | `width`, `height`, `caption` | | `pageBreak` | - | - |

Rich Text Support

Paragraphs and list items support rich text with inline formatting and links. Text can be:

• A simple string: `"Plain text"`
• An array of segments with formatting: `[{ "text": "bold", "bold": true }, { "text": " normal" }]`

**Auto-linking:** URLs (http:// or https://) in text are automatically converted to clickable hyperlinks.

**TextSegment properties:** | Property | Type | Description | |----------|------|-------------| | `text` | string | The text content (required) | | `bold` | boolean | Bold formatting | | `italic` | boolean | Italic formatting | | `underline` | boolean | Underline formatting | | `link` | string | URL - makes text a clickable hyperlink | | `color` | string | Text color as hex (e.g., "#FF0000") |

**Examples:**

// Simple paragraph (backward compatible)
{ "type": "paragraph", "text": "Plain text paragraph." }

// Paragraph with inline formatting
{ "type": "paragraph", "text": [
  { "text": "This has " },
  { "text": "bold", "bold": true },
  { "text": " and " },
  { "text": "italic", "italic": true },
  { "text": " text." }
]}

// Paragraph with link
{ "type": "paragraph", "text": [
  { "text": "Visit " },
  { "text": "our website", "link": "https://example.com" },
  { "text": " for more info." }
]}

// List with rich text items
{ "type": "bulletList", "items": [
  "Simple string item",
  [{ "text": "Item with " }, { "text": "bold part", "bold": true }],
  [{ "text": "Click ", "link": "https://docs.example.com" }]
]}

// Auto-linked URL (no explicit link property needed)
{ "type": "paragraph", "text": "Check out https://example.com for details." }

See `references/docx-js-api.md` for complete API reference.

Word Document Editing

For editing existing documents (especially with tracked changes), use the unpack-edit-repack workflow.

Step 1: Unpack

uvx --with defusedxml python ~/.pipali/skills/document-creator/scripts/docx_unpack.py \
  input.docx \
  --output unpacked_folder/

Step 2: Edit XML

Edit `unpacked_folder/word/document.xml` directly. Key elements:

• `<w:p>` - Paragraph
• `<w:r>` - Run (text span)
• `<w:t>` - Text content
• `<w:ins>` - Tracked insertion
• `<w:del>` - Tracked deletion

Use `scripts/docx_edit.py` for common operations:

# Find and replace with tracked changes
uvx --with defusedxml python scripts/docx_edit.py \
  --folder unpacked_folder/ \
  --action replace \
  --find "old text" \
  --replace "new text" \
  --track-changes \
  --author "Your Name"

Step 3: Repack

uvx --with defusedxml python ~/.pipali/skills/document-creator/scripts/docx_pack.py \
  unpacked_folder/ \
  --output output.docx

See `references/ooxml-structure.md` for XML element reference.

Excel Creation and Editing

Use `scripts/xlsx_create.py` for all Excel operations.

Running the Script

uvx --with openpyxl python ~/.pipali/skills/document-crea