DOCX

DOCX Document Skill

Create professional Word documents using docx (docx-js npm package) for all document generation, media-plugin for sourcing/generating images, and graph-generation for charts and diagrams.

Before you start: plan the visuals

If you are deciding the document's visuals yourself (a report/whitepaper/proposal that "should look good" or "needs diagrams"), run the visual-planning skill (media-plugin) FIRST. It decides which concepts deserve a visual, picks the right technique for each, and binds them to one style — then routes each to the correct engine. Skipping it is the main cause of ugly documents.

Routing rule (no exceptions): diagrams, charts, architecture, flows, and data viz go to the graph-generation skill (D3 / Mermaid / Draw.io) and are embedded as PNG. They are never produced via AI generate_image, which mangles labels and layout. AI image generation is only for photos, illustrations, backgrounds, and mockups.

Quick Reference

Setup

# Install dependencies (first time only)
npm install -g docx sharp
pip install "markitdown[docx]" Pillow --break-system-packages

# Verify LibreOffice is available (for thumbnail generation and PDF export)
which soffice || echo "LibreOffice not installed — install with: sudo apt install libreoffice"

# Verify pdftoppm is available (for thumbnail generation)
which pdftoppm || echo "pdftoppm not installed — install with: sudo apt install poppler-utils"

If LibreOffice or poppler-utils are not installed, tell the user they are needed for visual QA and ask if they'd like to install them. If the user declines or installation is not possible, skip visual QA and rely on structural checks.

Creating from Scratch

Step 1: Structure

Define the document outline — sections, headings, and purpose of each. Output: an ordered list of sections with their role.

Example:

1. Cover Page — title, subtitle, date, author
2. Executive Summary — key findings in 2-3 paragraphs
3. Introduction — background and scope
4. Analysis — data tables, charts, key metrics
5. Recommendations — prioritized action items
6. Appendix — supporting data

This step is about the skeleton — no content details yet.

Step 2: Content + Visual Plan

For each section, define:

1. Text content — headings, paragraphs, bullet points, tables, data
2. Image plan — which sections need images/charts and at what size
3. Chart plan — which data needs D3.js charts or Mermaid diagrams
4. Color palette — pick a palette matching the topic (see references/design.md)
5. Font pairing — pick header + body fonts (see references/design.md)

Design Quality Target

Read the Design System in references/design.md. Key requirements:

• Professional cover page with title, subtitle, date, author
• Consistent heading hierarchy (Heading1 for sections, Heading2 for subsections)
• Tables with header row shading and alternating row colors
• Images sized appropriately (full-width, half-width, or quarter-width)
• Page numbers in footer
• Table of Contents for documents > 3 pages

Step 3: Gather Visuals

Gather all planned images and charts BEFORE writing any code.

For each image:

1. Try Unsplash first — use the image-sourcing skill for real photos
2. Fall back to AI generation — use image-generation skill if no suitable stock photo exists

For each chart/diagram:

1. Use graph-generation skill for D3.js charts (bar, line, pie, scatter, area, etc.)
2. Use graph-generation skill for Mermaid diagrams (flowcharts, sequence, ER, C4, etc.)
3. Charts are rendered as PNG via Playwright, then embedded into the DOCX

Image Sizing for Documents

Step 4: Generate DOCX

Read references/docx-js-api.md for the full docx-js API reference.

Write a Node.js script that generates the .docx:

const docx = require("docx");
const fs = require("fs");

const { Document, Packer, Paragraph, TextRun, HeadingLevel, Table,
        TableRow, TableCell, WidthType, ImageRun, PageBreak,
        AlignmentType, BorderStyle, ShadingType, Header, Footer,
        PageNumber, NumberFormat, TableOfContents } = docx;

async function main() {
  const doc = new Document({
    creator: "Claude",
    title: "Document Title",
    styles: {
      default: {
        document: {
          run: { font: "Calibri", size: 24 }, // 12pt
        },
        heading1: {
          run: { font: "Georgia", size: 36, bold: true, color: "1B3A5C" },
          paragraph: { spacing: { before: 360, after: 120 } },
        },
        heading2: {
          run: { font: "Georgia", size: 28, bold: true, color: "2C5F8A" },
          paragraph: { spacing: { before: 240, after: 80 } },
        },
      },
    },
    sections: [{
      properties: {
        page: {
          size: { width: 12240, height: 15840 }, // US Letter
          margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }, // 1" margins
        },
      },
      headers: {
        default: new Header({
          children: [new Paragraph({ text: "Document Title", alignment: AlignmentType.RIGHT })],
        }),
      },
      footers: {
        default: new Footer({
          children: [new Paragraph({
            alignment: AlignmentType.CENTER,
            children: [
              new TextRun("Page "),
              new TextRun({ children: [PageNumber.CURRENT] }),
              new TextRun(" of "),
              new TextRun({ children: [PageNumber.TOTAL_PAGES] }),
            ],
          })],
        }),
      },
      children: [
        new Paragraph({
          heading: HeadingLevel.HEADING_1,
          text: "Section Title",
        }),
        new Paragraph({
          children: [new TextRun("Body text content here.")],
        }),
        // ... more content
      ],
    }],
  });

  const buffer = await Packer.toBuffer(doc);
  fs.writeFileSync("output.docx", buffer);
  console.log("Done: output.docx");
}

main().catch(console.error);

Critical Rules (violating these corrupts or breaks the DOCX)

• Page dimensions in DXA — US Letter = 12240 x 15840, A4 = 11906 x 16838 (1 inch = 1440 DXA)
• Never use \n for line breaks — use separate Paragraph elements
• Tables: always use WidthType.DXA, set both columnWidths on Table and width on each cell
• Lists: use LevelFormat.BULLET for bullets, never manual bullet characters
• Page breaks: use PageBreak inside a Paragraph's children array
• Images: always specify type parameter (e.g., ImageRun with explicit dimensions)
• Heading IDs: use "Heading1", "Heading2" + set outlineLevel for TOC compatibility

Step 5: QA

After generating the .docx, verify with a rigorous QA process.

5a: Visual QA (thumbnail subagent)

Generate page thumbnails and visually inspect via a subagent:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/docx/scripts/thumbnail.py output.docx thumbnails

Then launch a subagent to inspect the generated page images. Check for:

• Text overflowing margins
• Tables not fitting the page width
• Images distorted or poorly positioned
• Inconsistent heading styles
• Missing page numbers
• Blank pages (common with page breaks)

5b: Schema Validation

Validate the DOCX against OOXML XSD schemas:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/office/validate.py output.docx -v

If validation fails, use --auto-repair to fix common issues, or inspect errors and fix the generation script.

5c: Structural QA

Check for placeholder text and structural issues:

python -m markitdown output.docx

Review for:

• Missing text or wrong section order
• Placeholder text ("Lorem ipsum", "TODO", "Insert text here")
• Typos and data accuracy

5d: Placeholder Grep

python -m markitdown output.docx | grep -iE "(lorem|ipsum|placeholder|todo|tbd|insert|example|sample text)"

Step 6: Fix & Re-verify

If QA reveals issues:

1. Fix the generation script
2. Re-run to generate a new .docx
3. Re-run QA (Step 5)
4. Repeat until clean

Editing from Template

For editing existing DOCX files (updating content, tracked changes, comments), see editing.md.

Reading Content

To extract text content from an existing DOCX:

python -m markitdown output.docx

To generate visual page thumbnails:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/docx/scripts/thumbnail.py input.docx thumbnails

Chart Integration

The DOCX skill integrates with the graph-generation skill for embedding charts and diagrams.

D3.js Charts

Use graph-generation to create data visualizations:

• Bar charts, line charts, pie charts, scatter plots
• Area charts, grouped/stacked bars
• Charts rendered as PNG, then embedded into DOCX via ImageRun

Mermaid Diagrams

Use graph-generation to create diagrams:

• Flowcharts, sequence diagrams, ER diagrams
• C4 architecture diagrams, state diagrams
• Diagrams rendered as PNG via Playwright, then embedded into DOCX

Embedding Charts

// After generating chart PNG via graph-generation skill
const chartData = fs.readFileSync("chart.png");
new Paragraph({
  children: [
    new ImageRun({
      data: chartData,
      transformation: { width: 468, height: 300 }, // ~6.5" x ~4.2" at 72 DPI
      type: "png",
    }),
  ],
  alignment: AlignmentType.CENTER,
});

Scripts

Shared Office Scripts

DOCX-Specific Scripts

Reference Files

Read the reference files before generating any document.