| name | docx |
| description | 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). |
| license | MIT |
| metadata | {"version":"0.1.0","author":"BRICKS"} |
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.
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
- 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.
- 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).
- 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.
