DOCX Generator Agent Skill

DOCX Generator

When to Use This Skill

Use this skill when:

• Creating Word documents programmatically from data or specifications
• Populating branded templates with dynamic content while preserving corporate styling
• Extracting text, tables, and structure from existing DOCX files for analysis
• Finding and replacing placeholder text like {{TITLE}} or ${author}
• Automating document generation workflows (reports, contracts, letters)

Do NOT use this skill when:

• User wants to open/view documents (use native Word or viewer)
• Complex mail merge with data sources (use native Word mail merge)
• Working with older .doc format (DOCX only)
• PDF output is needed (use pdf-generator skill instead)

Prerequisites

• Deno installed (https://deno.land/)
• Input DOCX files for template-based operations
• JSON specification for scratch generation

Quick Start

Two Modes of Operation

• Template Mode: Modify existing branded templates
• Analyze template to find placeholders
• Replace {{PLACEHOLDERS}} with actual content

• Scratch Mode: Create documents from nothing using JSON specifications

Instructions

Mode 1: Template-Based Generation

Step 1a: Analyze the Template

Extract text inventory to understand what can be replaced:

deno run --allow-read scripts/analyze-template.ts corporate-template.docx > inventory.json

Output (inventory.json):

{
  "filename": "corporate-template.docx",
  "paragraphCount": 25,
  "tableCount": 2,
  "imageCount": 1,
  "paragraphs": [
    {
      "index": 0,
      "style": "Title",
      "fullText": "{{DOCUMENT_TITLE}}",
      "runs": [
        { "text": "{{DOCUMENT_TITLE}}", "bold": true, "fontSize": 28 }
      ]
    }
  ],
  "placeholders": [
    { "tag": "{{DOCUMENT_TITLE}}", "location": "paragraph", "paragraphIndex": 0 },
    { "tag": "{{AUTHOR}}", "location": "footer-default", "paragraphIndex": 0 },
    { "tag": "${date}", "location": "table", "tableIndex": 0, "cellLocation": "R1C2" }
  ]
}

Step 1b: Create Replacement Specification

Create replacements.json:

{
  "textReplacements": [
    { "tag": "{{DOCUMENT_TITLE}}", "value": "Q4 2024 Financial Report" },
    { "tag": "{{AUTHOR}}", "value": "Finance Department" },
    { "tag": "${date}", "value": "December 15, 2024" },
    { "tag": "{{COMPANY}}", "value": "Acme Corporation" }
  ],
  "includeHeaders": true,
  "includeFooters": true
}

Step 1c: Generate Output

deno run --allow-read --allow-write scripts/generate-from-template.ts \
  corporate-template.docx replacements.json output.docx

Mode 2: From-Scratch Generation

Step 2a: Create Specification

Create spec.json:

{
  "title": "Quarterly Report",
  "creator": "Finance Team",
  "styles": {
    "defaultFont": "Calibri",
    "defaultFontSize": 11
  },
  "sections": [
    {
      "header": {
        "paragraphs": [
          { "text": "Acme Corporation", "alignment": "right" }
        ]
      },
      "footer": {
        "paragraphs": [
          { "text": "Confidential", "alignment": "center" }
        ]
      },
      "content": [
        {
          "text": "Q4 2024 Financial Report",
          "heading": 1,
          "alignment": "center"
        },
        {
          "runs": [
            { "text": "Executive Summary: ", "bold": true },
            { "text": "This report provides an overview of our financial performance for Q4 2024." }
          ]
        },
        { "pageBreak": true },
        {
          "text": "Revenue Breakdown",
          "heading": 2
        },
        {
          "rows": [
            {
              "cells": [
                { "content": [{ "text": "Category" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Amount" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Change" }], "shading": "DDDDDD" }
              ],
              "isHeader": true
            },
            {
              "cells": [
                { "content": [{ "text": "Product Sales" }] },
                { "content": [{ "text": "$1,250,000" }] },
                { "content": [{ "text": "+15%" }] }
              ]
            },
            {
              "cells": [
                { "content": [{ "text": "Services" }] },
                { "content": [{ "text": "$750,000" }] },
                { "content": [{ "text": "+8%" }] }
              ]
            }
          ],
          "width": 100,
          "borders": true
        }
      ]
    }
  ]
}

Step 2b: Generate Document

deno run --allow-read --allow-write scripts/generate-scratch.ts spec.json output.docx

Examples

Example 1: Contract Generation

Scenario: Generate contracts from a branded template.

Steps:

# 1. Analyze template for replaceable content
deno run --allow-read scripts/analyze-template.ts contract-template.docx --pretty

# 2. Create replacements.json with client data
# 3. Generate contract
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  contract-template.docx replacements.json acme-contract.docx

Example 2: Report with Tables

Scenario: Generate a data report with tables and formatting.

spec.json:

{
  "title": "Sales Report",
  "sections": [{
    "content": [
      { "text": "Monthly Sales Report", "heading": 1 },
      { "text": "January 2025", "heading": 2 },
      {
        "runs": [
          { "text": "Total Sales: ", "bold": true },
          { "text": "$125,000", "color": "2E7D32" }
        ]
      }
    ]
  }]
}

Example 3: Letter with Headers/Footers

Scenario: Create a formal letter with letterhead.

spec.json:

{
  "sections": [{
    "header": {
      "paragraphs": [
        { "text": "ACME CORPORATION", "alignment": "center", "runs": [{"text": "ACME CORPORATION", "bold": true, "fontSize": 16}] },
        { "text": "123 Business Ave, City, ST 12345", "alignment": "center" }
      ]
    },
    "content": [
      { "text": "December 15, 2024", "alignment": "right" },
      { "text": "" },
      { "text": "Dear Valued Customer," },
      { "text": "" },
      { "text": "Thank you for your continued business..." },
      { "text": "" },
      { "text": "Sincerely," },
      { "text": "John Smith" },
      { "runs": [{ "text": "CEO", "italic": true }] }
    ],
    "footer": {
      "paragraphs": [
        { "text": "www.acme.com | [email protected]", "alignment": "center" }
      ]
    }
  }]
}

Script Reference

| Script | Purpose | Permissions |

|--------|---------|-------------|

| analyze-template.ts | Extract text, tables, placeholders from DOCX | --allow-read |

| generate-from-template.ts | Replace placeholders in templates | --allow-read --allow-write |

| generate-scratch.ts | Create DOCX from JSON specification | --allow-read --allow-write |

Specification Reference

Paragraph Options

| Property | Type | Description |

|----------|------|-------------|

| text | string | Simple text content |

| runs | array | Formatted text runs (for mixed formatting) |

| heading | 1-6 | Heading level |

| alignment | string | left, center, right, justify |

| bullet | boolean | Bulleted list item |

| numbering | boolean | Numbered list item |

| spacing | object | before, after, line spacing |

| indent | object | left, right, firstLine indentation |

| pageBreakBefore | boolean | Insert page break before paragraph |

Text Run Options

| Property | Type | Description |

|----------|------|-------------|

| text | string | Text content |

| bold | boolean | Bold formatting |

| italic | boolean | Italic formatting |

| underline | boolean | Underline formatting |

| strike | boolean | Strikethrough |

| fontSize | number | Font size in points |

| font | string | Font family name |

| color | string | Text color (hex, no #) |

| highlight | string | Highlight color |

| superScript | boolean | Superscript |

| subScript | boolean | Subscript |

Table Options

| Property | Type | Description |

|----------|------|-------------|

| rows | array | Array of row specifications |

| width | number | Table width as percentage |

| borders | boolean | Show table borders |

Hyperlink Options

| Property | Type | Description |

|----------|------|-------------|

| text | string | Link text |

| url | string | Target URL |

| bold | boolean | Bold formatting |

| italic | boolean | Italic formatting |

Common Issues and Solutions

Issue: Placeholders not being replaced

Symptoms: Output DOCX still contains {{PLACEHOLDER}} tags.

Solution:

• Run analyze-template.ts to verify exact tag text
• Tags may be split across XML runs - the script consolidates these automatically
• Ensure includeHeaders and includeFooters are true if placeholders are there

Issue: Formatting lost after replacement

Symptoms: Replaced text doesn't match original formatting.

Solution:

• Text replacement preserves the formatting of the original placeholder
• Ensure placeholder is formatted the way you want the final text to appear

Issue: Images not appearing

Symptoms: Image elements are blank in output.

Solution:

• Use paths relative to the spec.json file location
• Verify image file exists and is readable
• Check supported formats: PNG, JPEG, GIF

Issue: Table cell content incorrect

Symptoms: Table cells have wrong content or formatting.

Solution:

• Each cell's content must be an array of paragraph specifications
• Use shading for background color, verticalAlign for alignment

Limitations

• DOCX only: Does not support legacy .doc format
• No track changes: Cannot add or process track changes
• No comments: Cannot add document comments
• No macros: Cannot include VBA macros
• Basic numbering: Limited support for complex numbering schemes
• Text run splitting: Word may split text across XML elements; script handles common cases

Related Skills

• pptx-generator: For creating PowerPoint presentations
• xlsx-generator: For creating Excel spreadsheets
• pdf-generator: For creating PDF documents