# DOCX

> Use when the user brings a Word document (.docx) into their BRICKS project and wants its content in the app — menus, price lists, policies, product sheets, event programs, manuals, service guides. Extracts headings, paragraphs, lists, tables, and embedded images on the design machine with a bundled zero-dependency script; routes the results into Data entries, Property Bank values, data-calculation sources, or media assets, and can feed the vectorStore for document Q&A. Covers re-import when the document changes and runtime ingestion for apps that accept uploaded documents. Triggers on "import this Word document", "use this docx", "read the menu from this Word file", or a .docx path in the prompt. Do NOT use to create or edit Word files as the deliverable, and not for PDFs, spreadsheets, or slide decks (use the pdf / xlsx / pptx skills).

- Skill: `mybigday/docx` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mybigday/docx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mybigday/docx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- License: MIT
- Author: mybigday (https://skillmd.com/u/mybigday)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mybigday/docx

---


# Word Document Import

Turn a Word document into live app content: Data entries, Property Bank
values, media assets, or searchable knowledge.

**Announce at start:** "I'm using the docx skill to import this document."

## Step 1: Extract

Run the bundled script. Resolve the path against this skill directory (the
directory containing this SKILL.md) and pass the absolute script path to `bun`
as a single command — no pipes or chaining. Zero dependencies, fully offline.

```bash
bun /absolute/path/to/docx/scripts/docx_extract.ts document.docx --out output/import/document.json --extract-media output/import/document-media
```

The JSON contains `blocks` in document order — `heading` (with level;
localized heading styles and Title are recognized), `paragraph`, `list-item`
(with indent level), and `table` (rows of cell strings) — plus extracted
`media` paths. Legacy `.doc` and `.odt` are unsupported — ask for a `.docx`
export.

Extraction rules to keep in mind:

- **Structure needs styles.** Documents authored without Word's heading/list
  styles (pure direct formatting, some converters) come out as plain
  paragraphs — infer the structure from the text yourself.
- **Tables:** vertically merged cells carry text only in the top cell
  (continuations are empty strings); nested tables flatten into their
  containing cell's text.
- **Tracked changes** export as if accepted; hyperlinks keep their text but
  lose the URL.
- **Not extracted:** headers, footers, footnotes, comments.

## Step 2: Choose the destination

| Content | Destination | Why |
|---|---|---|
| A few values used in fixed places (title, phone, tagline, opening hours) | Brick properties / Property Bank values | simplest; no indirection |
| Lists and tables the UI iterates (menu items, products, schedule rows) | **Data entries** (project Data, edited with `edit_entry`) | structured, drives list UIs |
| Long-form content users will search or ask questions about (manuals, policies) | vectorStore ingestion (see `ai-recipes` doc-qa pattern) | semantic search / RAG |
| Embedded images worth showing (photos, logos, illustrations) | `media_upload_files` → Image / Slideshow bricks | reuses the document's own assets |

Default for tabular content: Data entries. Ask the user only when the choice
changes the app's structure.

## Step 3: Shape and import

1. Use the heading hierarchy to segment content — headings usually delimit the
   categories or sections a screen iterates. Word tables usually map 1:1 to a
   Data list with the first row as column names. Write the structured result
   to `output/import/<name>.json` so the mapping is reviewable.
2. Import:
   - Data entries: use the `edit_entry` tool (Data type). Derive stable keys
     from a natural field (item name, SKU) — not from block order — so
     re-imports update instead of duplicate.
   - Property values: set brick properties or Property Bank initial values via
     the project editing tools.
   - Embedded images: upload the `--extract-media` output with
     `media_upload_files` (if the media tools are unavailable, ask the user to
     upload via the Controller UI).
3. Record provenance at the top of the JSON file: source path, extraction
   date, and the field mapping.

## Step 4: Verify

Preview in the simulator: spot-check imported values against the source
document — first item, last item, and one from the middle. Check currency,
dates, and phone-number formatting survived, and that every uploaded image
renders.

## Runtime ingestion (apps that accept documents while running)

For apps that must ingest user-provided documents at runtime, don't parse at
design time — wire the app itself:

- The `vectorStore` generator's insert-file command ingests Word / Office /
  OpenOffice documents into searchable chunks — works on **all launchers**
  (unlike PDF, which is web/desktop only at runtime).
- Data calculations can call `parseDocument(path)` for text extraction.

Both give **text**, not structured blocks — for structured runtime data,
prefer the Data Bank flow (update data in the cloud, devices subscribe via the
dataBank generator) over runtime file parsing.

## Re-import (the document changed)

Re-run Step 1, diff the new blocks JSON against the previous one (headings,
tables, counts), report changes to the user, and update Data entries by stable
key. Never wholesale-delete entries unless asked.

## When Not To Use

- The deliverable is a Word file (creating/editing .docx) — out of scope.
- The file is a PDF, spreadsheet, or slide deck — use the `pdf` / `xlsx` /
  `pptx` skills.
- The user pasted the text already — just use it directly.