Word

Table of contents

1. How it works with an AI agent

User: "Create a Q3 report as a Word file, A4, with a table of contents"
  |
  v
AI Agent (CoDev Code / OpenCode / Claude Code / Codex / Cursor / ...)
  | 1. Sees trigger signals (Word, docx, report...) -> loads SKILL.md
  | 2. Runs scripts/env_check.sh - must be READY before proceeding
  | 3. Routes: no input file -> Pipeline A: CREATE
  | 4. Reads references/scenario_a_create.md + typography_guide.md
  | 5. Generates content + picks the matching aesthetic recipe
  | 6. Executes: calls the CLI (dotnet run ... create ...) or
  |    writes C# for complex tasks
  | 7. Validates: merge-runs -> XSD validate -> business validate
  |    (on failure -> fix-order -> re-validate; Pipeline C adds a
  |    mandatory gate-check)
  | 8. Previews and delivers the file
  v
Finished .docx + validation report

The key point: steps 3–7 are orchestrated by the LLM following SKILL.md. The user is involved only at the start (describe the request) and the end (acceptance).

The skill routes every task down one of three pipelines:

2. Prerequisites

Set these up first — Install skills walks through the install on Windows, macOS and Ubuntu step by step; its Install the skills into an agent section covers installing the skill into each agent (CoDev Code, OpenCode, Claude Code, Codex, Cursor) by hand.

The machine running the agent needs:

• .NET SDK 8.0+ (required — the agent builds the CLI from source on first run)
• pandoc (optional — previews)
• LibreOffice soffice (optional — legacy .doc conversion)
• Windows: Git Bash or WSL (for the .sh scripts)

3. How to use it: talk to the agent

The skill self-activates when your prompt contains its signals: Word, docx, document, report, contract, proposal, memo, reformat, apply template… (even without the word "docx" — any task whose final output is a printable/formal document qualifies).

Golden rule — provide these 4 groups of information:

1. What: create new / fill-edit / apply a template (the agent can infer, but explicit is better)
2. Which files: input and output files — a plain name plus "in this folder" (a.docx), or a full path (C:\temp\a.docx, ~/docs/a.docx)
3. Content/structure: title, sections, heading levels, table data, placeholder values
4. Appearance: document type (report/letter/memo/academic), page size, margins, font, reference style

4. Prompt recipes per task type

4.1. Create new (Pipeline A — CREATE)

Create a Word report q3_report.docx in this folder:
- Title: "Q3/2026 Report", author: IT Department
- A4, 2 cm margins, page numbers, and a table of contents
- Section 1 (H1): Overview — summary of the quarter
- Section 2 (H1): Detailed results
    - 2.1 (H2): Revenue — with a 3-column table: Product | Qty | Revenue,
      data: A|100|$1.2M, B|250|$2.8M
    - 2.2 (H2): Headcount
- Section 3 (H1): Conclusions and recommendations
Formal tone; write the body content from the bullets above.

Tip: name the document type (report/letter/memo/academic) so the agent picks the right default fonts and aesthetic recipe (academic → APA/IEEE recipes). You can also request a recipe by name — the skill ships tested recipes with exact values taken from the official style guides: ModernCorporate, AcademicThesis, ExecutiveBrief, MinimalModern, IEEE Conference, ACM sigconf, APA 7th, MLA 9th, Chicago/Turabian, Springer LNCS, Nature, and HBR.

4.2. Fill / edit an existing file (Pipeline B — FILL-EDIT)

# Replace text:
In contract.docx in this folder, replace every "Company A" with
"Acme Corp", save to contract_final.docx. Keep all formatting intact.
 
# Fill placeholders:
contract_template.docx in this folder contains {{name}}-style placeholders.
List them first, then fill: fullname = "John Smith",
dob = "1990-01-01", address = "Hanoi". Output to contract_JS.docx.
 
# Load table data:
Fill the first table of staff.docx in this folder with staff.csv
(keep the table's header row, replace all existing data rows).
 
# Insert content:
Append an "Appendix" section (Heading 1) at the end of report.docx
in this folder, containing the list of references.

Important tip: locate positions by text content ("after the Conclusion section"), never by row/paragraph numbers — Word files may contain blank or merged rows that shift indices.

Placeholders are not limited to {{name}} — the skill accepts a custom regex pattern (--pattern), so templates using <<name>> or [name] markers work too; just show the agent one example of your marker style.

4.3. Apply a template / reformat (Pipeline C — FORMAT-APPLY)

Apply template formatting to a content file in this folder:
- Template: corporate.docx (company style)
- Content file: content.docx
- Output: result.docx
Requirements: preserve 100% of the content, change formatting only.
Keep the template's TOC, headers/footers, and page numbers.
Run the gate-check and report the result to me.

For complex templates (cover + TOC + many sections with per-section headers/footers — thesis/official-document style), say so explicitly so the agent picks the C-2 Base-Replace strategy (template as the base, replace its example content) instead of just copying styles.

The skill also handles multi-template merge: when the formatting comes as several files (e.g. one template for fonts, one for headings, one for section breaks), say which file plays which role — the agent merges all styles into one set and takes the document structure from the breaks template.

4.4. Complex tasks (the agent will write C#)

These exceed the CLI — the agent writes C# from the Samples; you only describe:

# Example: multi-section document with images
Create profile.docx in this folder: a cover page with logo.png centered,
then a TOC, a two-column body, a per-chapter "Page X / Y" footer,
and every chapter starting on an odd page.
 
# Example: track changes
In contract_v2.docx in this folder, change the payment term from 30 to
45 days AS TRACKED CHANGES so the counterparty can review them.
 
# Example: footnotes and cross-references
In thesis.docx in this folder, add a footnote to the phrase "hybrid
approach" in chapter 2 citing the 2025 whitepaper, and turn every
"see Figure 3" into a live REF field pointing at the figure caption.
 
# Example: mail-merge fields
Turn offer_letter.docx in this folder into a mail-merge template: replace
the name, salary and start-date values with MERGEFIELD fields and put a
DATE field in the header.
 
# Example: a real equation
Under the "Energy" heading of physics.docx in this folder, insert E = mc²
as a native Word equation (OMML), not as an image.

4.5. Convert and analyze

Convert the legacy file document.doc in this folder to .docx and describe
its structure (sections, styles, number of tables).
 
Compare v1.docx with v2.docx in this folder and list the differences.

The structure report (analyze) covers sections, the heading tree, table dimensions, image/header/footer counts, word count and custom styles; both analyze and diff have a --json mode when you want the complete machine-readable output.

4.6. Review workflows: comments and tracked changes

The skill covers the full Word review cycle: the modern comment system (threaded replies, resolve status) and revision marks in both directions — proposing changes (see the track-changes example in 4.4) as well as processing someone else's.

# Add a comment:
In contract.docx in this folder, add a comment on the "Liability" clause:
"Legal: please confirm the cap amount" (author: M. Nguyen).
 
# Reply and resolve:
List all open comments in contract_v2.docx in this folder, reply
"Confirmed — 2x annual fees" to the liability comment, and mark it resolved.
 
# Accept / reject revisions:
contract_v3.docx in this folder came back full of tracked changes. Accept
them all EXCEPT the ones inside the "Payment terms" section — reject those —
and save a clean copy to contract_final.docx.
 
# Protect the deliverable:
Finalize policy.docx in this folder: apply write protection with the password
"review2026" so reviewers can only add comments, not edit the text.

5. Acceptance — make the agent prove it

SKILL.md mandates a validation process the agent must run after every write. You are entitled to (and should) ask for evidence:

"Run the full validation pipeline and show me the results"

A passing delivery includes:

• validate --xsd → Validation: PASSED (ISO 29500 structure)
• validate --business → PASSED (font consistency, structural sanity)
• For template tasks: GATE CHECK: PASSED — SKILL.md states do not deliver until the gate-check passes; the agent must fix and re-run until it does.
• For edit tasks: diff --before --after showing exactly what changed (proof of minimal changes — nothing else was disturbed).

If the agent delivers without mentioning validation — ask. Finally, always open the file in Word/LibreOffice for a visual check (press F9 in Word to populate the TOC).

6. Troubleshooting

7. Skill limitations

• Handles .docx (OpenXML) only; legacy .doc must be converted first (needs LibreOffice).
• Cannot read password-encrypted input files. (Applying write protection to output files is supported — see 4.6.)
• No OCR of images/scans.
• The TOC is a field — Word computes it (F9); the skill does not pre-render it.
• All operations go through the OpenXML SDK; the skill avoids open-and-resave conversion libraries, which can destroy VBA macros and fields.

8. Appendix: the CLI the agent runs under the hood

So you can read the agent's logs ($CLI = dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --):

--content-json payload: an array of [{"type":"heading","text":"…","level":1..6}, {"type":"paragraph","text":"…"}, {"type":"pagebreak"}]. In text mode diff prints only the first 20 text changes — use --json for the complete list.

Note for agents/code readers: SKILL.md diverges from the actual CLI in places — the real flags are --search (not --find) and --mapping <file> (not --data); insert-section/remove-section/update-header-footer are not implemented (the agent writes C# for those instead); validate --gate-check expects a template DOCX to compare against, not the XSD file shown in SKILL.md's example; and the run-script command in SKILL.md's C# scaffold does not exist — custom C# runs as its own console project instead.