Office DOCX
Use the bundled scripts in this skill package to produce editable .docx
files. The builder writes deterministic OOXML with real Word numbering,
tables, images with alt text, comments, and tracked changes. The skill
activation metadata includes Skill directory; treat that as SKILL_DIR and
run scripts from SKILL_DIR/scripts/.
Workflow
- Decide the document archetype: brief, proposal, SOP, form, checklist,
report, memo, or reference guide.
- Create a JSON spec in the working directory. Use semantic blocks:
heading, paragraph, bullet_list, numbered_list, table, callout,
image, comment, revision, and page_break.
- For a new document, run:
python3 "$SKILL_DIR/scripts/check_env.py"
python3 "$SKILL_DIR/scripts/build_docx.py" --spec spec.json --out output.docx
python3 "$SKILL_DIR/scripts/inspect_docx.py" --verify output.docx
python3 "$SKILL_DIR/scripts/a11y_audit.py" output.docx
- To append to an existing document, use a spec containing only the new
blocks, then run:
python3 "$SKILL_DIR/scripts/append_docx.py" --input existing.docx --spec append.json --out output.docx
python3 "$SKILL_DIR/scripts/inspect_docx.py" --verify output.docx
- To convert a Markdown draft directly:
python3 "$SKILL_DIR/scripts/markdown_to_docx.py" --markdown draft.md --out output.docx
python3 "$SKILL_DIR/scripts/inspect_docx.py" --verify output.docx
- For Google Docs-targeted output, sanitize before render/import:
python3 "$SKILL_DIR/scripts/google_docs_title_sanitize.py" output.docx --out sanitized.docx
python3 "$SKILL_DIR/scripts/google_docs_title_sanitize.py" sanitized.docx --check
Use sanitized.docx for preview rendering and native Google Docs import.
- For redline/comment work, use
comment blocks or revision blocks:
{"type": "comment", "target": "This sentence needs support.", "comment": "Add source."}
{"type": "revision", "delete": "old wording", "insert": "new wording"}
- For delivery cleanup, use the focused helpers:
python3 "$SKILL_DIR/scripts/comments_strip.py" commented.docx --out no-comments.docx
python3 "$SKILL_DIR/scripts/comments_extract.py" commented.docx
python3 "$SKILL_DIR/scripts/add_tracked_replacements.py" --input input.docx --spec replacements.json --out redlined.docx
python3 "$SKILL_DIR/scripts/accept_tracked_changes.py" redlined.docx --mode accept --out accepted.docx
python3 "$SKILL_DIR/scripts/redact_docx.py" input.docx redacted.docx --emails --phones
python3 "$SKILL_DIR/scripts/privacy_scrub_metadata.py" input.docx --out scrubbed.docx
python3 "$SKILL_DIR/scripts/compare_docx.py" before.docx after.docx
- For advanced Word structure tasks, use the focused OOXML helpers:
python3 "$SKILL_DIR/scripts/insert_toc.py" input.docx --out with-toc.docx
python3 "$SKILL_DIR/scripts/fields_report.py" with-toc.docx
python3 "$SKILL_DIR/scripts/insert_note.py" input.docx --kind footnote --text "Source note" --out with-note.docx
python3 "$SKILL_DIR/scripts/watermark_add.py" input.docx --text "DRAFT" --out watermarked.docx
python3 "$SKILL_DIR/scripts/watermark_audit_remove.py" watermarked.docx
python3 "$SKILL_DIR/scripts/set_protection.py" input.docx --mode readOnly --out protected.docx
python3 "$SKILL_DIR/scripts/content_controls.py" input.docx --spec controls.json --out form.docx
python3 "$SKILL_DIR/scripts/internal_nav.py" input.docx --spec nav.json --out linked.docx
python3 "$SKILL_DIR/scripts/merge_docx_append.py" --input a.docx --input b.docx --out merged.docx
python3 "$SKILL_DIR/scripts/docx_table_to_csv.py" input.docx --out-dir tables
- If visual QA matters and LibreOffice is available, render previews:
python3 "$SKILL_DIR/scripts/render_preview.py" output.docx
- Deliver the
.docx path or attach it with send_attachment.
Spec Shape
{
"title": "Document title",
"subtitle": "Optional subtitle",
"blocks": [
{"type": "heading", "level": 1, "text": "Section"},
{"type": "paragraph", "text": "Body copy."},
{"type": "bullet_list", "items": ["Point one", {"text": "Point two", "comment": "Verify"}]},
{"type": "image", "path": "chart.png", "alt": "Revenue trend chart", "caption": "Figure 1. Revenue trend", "width_inches": 5.5, "height_inches": 3.2},
{"type": "revision", "delete": "Old sentence.", "insert": "Improved sentence."},
{"type": "table", "headers": ["Metric", "Value"], "rows": [["ARR", "$1.2M"]]}
]
}
Quality Bar
- Keep documents editable: use semantic headings, real Word lists, comments,
tracked changes, images with alt text, and real tables.
- Run
a11y_audit.py before delivery; fix hard issues such as fake bullets,
missing image alt text, empty documents, and structural defects.
- Do not overuse tables for normal prose.
- Avoid dense walls of text unless the document type demands it.
- For Google Docs-targeted output, keep the title simple and native-looking and
run
google_docs_title_sanitize.py --check.
- When editing existing DOCX packages, preserve package structure: append body
content before the final
w:sectPr, keep existing headers/relationships, and
let watermark helpers allocate a new header part instead of replacing one.
- If preview rendering fails because LibreOffice or a PDF-to-PNG renderer is
missing, state exactly which verification passed; do not imply visual QA
passed.
1---
2name: office-docx
3description: "Use when the user asks to create, edit, inspect, polish, verify, or deliver Word `.docx` documents, Google Docs-targeted drafts, business briefs, forms, reports, tables, checklists, redraft-ready document sections, or PDF/Word source-to-DOCX transformations."
4requires:
5 bins: [python3]
6install:
7 - kind: brew
8 formula: python
9 bins: [python3]
10 label: "Install Python 3 via Homebrew"
11 os: [darwin]
12allowed-tools:
13 - read
14 - write
15 - edit
16 - apply_patch
17 - exec
18 - ls
19 - grep
20 - pdf
21 - web_search
22 - web_fetch
23 - send_attachment
24---
25
26# Office DOCX
27
28Use the bundled scripts in this skill package to produce editable `.docx`
29files. The builder writes deterministic OOXML with real Word numbering,
30tables, images with alt text, comments, and tracked changes. The skill
31activation metadata includes `Skill directory`; treat that as `SKILL_DIR` and
32run scripts from `SKILL_DIR/scripts/`.
33
34## Workflow
35
361. Decide the document archetype: brief, proposal, SOP, form, checklist,
37 report, memo, or reference guide.
382. Create a JSON spec in the working directory. Use semantic blocks:
39 `heading`, `paragraph`, `bullet_list`, `numbered_list`, `table`, `callout`,
40 `image`, `comment`, `revision`, and `page_break`.
413. For a new document, run:
42
43```bash
44python3 "$SKILL_DIR/scripts/check_env.py"
45python3 "$SKILL_DIR/scripts/build_docx.py" --spec spec.json --out output.docx
46python3 "$SKILL_DIR/scripts/inspect_docx.py" --verify output.docx
47python3 "$SKILL_DIR/scripts/a11y_audit.py" output.docx
48```
49
504. To append to an existing document, use a spec containing only the new
51 `blocks`, then run:
52
53```bash
54python3 "$SKILL_DIR/scripts/append_docx.py" --input existing.docx --spec append.json --out output.docx
55python3 "$SKILL_DIR/scripts/inspect_docx.py" --verify output.docx
56```
57
585. To convert a Markdown draft directly:
59
60```bash
61python3 "$SKILL_DIR/scripts/markdown_to_docx.py" --markdown draft.md --out output.docx
62python3 "$SKILL_DIR/scripts/inspect_docx.py" --verify output.docx
63```
64
656. For Google Docs-targeted output, sanitize before render/import:
66
67```bash
68python3 "$SKILL_DIR/scripts/google_docs_title_sanitize.py" output.docx --out sanitized.docx
69python3 "$SKILL_DIR/scripts/google_docs_title_sanitize.py" sanitized.docx --check
70```
71
72Use `sanitized.docx` for preview rendering and native Google Docs import.
73
747. For redline/comment work, use `comment` blocks or `revision` blocks:
75
76```json
77{"type": "comment", "target": "This sentence needs support.", "comment": "Add source."}
78{"type": "revision", "delete": "old wording", "insert": "new wording"}
79```
80
818. For delivery cleanup, use the focused helpers:
82
83```bash
84python3 "$SKILL_DIR/scripts/comments_strip.py" commented.docx --out no-comments.docx
85python3 "$SKILL_DIR/scripts/comments_extract.py" commented.docx
86python3 "$SKILL_DIR/scripts/add_tracked_replacements.py" --input input.docx --spec replacements.json --out redlined.docx
87python3 "$SKILL_DIR/scripts/accept_tracked_changes.py" redlined.docx --mode accept --out accepted.docx
88python3 "$SKILL_DIR/scripts/redact_docx.py" input.docx redacted.docx --emails --phones
89python3 "$SKILL_DIR/scripts/privacy_scrub_metadata.py" input.docx --out scrubbed.docx
90python3 "$SKILL_DIR/scripts/compare_docx.py" before.docx after.docx
91```
92
939. For advanced Word structure tasks, use the focused OOXML helpers:
94
95```bash
96python3 "$SKILL_DIR/scripts/insert_toc.py" input.docx --out with-toc.docx
97python3 "$SKILL_DIR/scripts/fields_report.py" with-toc.docx
98python3 "$SKILL_DIR/scripts/insert_note.py" input.docx --kind footnote --text "Source note" --out with-note.docx
99python3 "$SKILL_DIR/scripts/watermark_add.py" input.docx --text "DRAFT" --out watermarked.docx
100python3 "$SKILL_DIR/scripts/watermark_audit_remove.py" watermarked.docx
101python3 "$SKILL_DIR/scripts/set_protection.py" input.docx --mode readOnly --out protected.docx
102python3 "$SKILL_DIR/scripts/content_controls.py" input.docx --spec controls.json --out form.docx
103python3 "$SKILL_DIR/scripts/internal_nav.py" input.docx --spec nav.json --out linked.docx
104python3 "$SKILL_DIR/scripts/merge_docx_append.py" --input a.docx --input b.docx --out merged.docx
105python3 "$SKILL_DIR/scripts/docx_table_to_csv.py" input.docx --out-dir tables
106```
107
10810. If visual QA matters and LibreOffice is available, render previews:
109
110```bash
111python3 "$SKILL_DIR/scripts/render_preview.py" output.docx
112```
113
11411. Deliver the `.docx` path or attach it with `send_attachment`.
115
116## Spec Shape
117
118```json
119{
120 "title": "Document title",
121 "subtitle": "Optional subtitle",
122 "blocks": [
123 {"type": "heading", "level": 1, "text": "Section"},
124 {"type": "paragraph", "text": "Body copy."},
125 {"type": "bullet_list", "items": ["Point one", {"text": "Point two", "comment": "Verify"}]},
126 {"type": "image", "path": "chart.png", "alt": "Revenue trend chart", "caption": "Figure 1. Revenue trend", "width_inches": 5.5, "height_inches": 3.2},
127 {"type": "revision", "delete": "Old sentence.", "insert": "Improved sentence."},
128 {"type": "table", "headers": ["Metric", "Value"], "rows": [["ARR", "$1.2M"]]}
129 ]
130}
131```
132
133## Quality Bar
134
135- Keep documents editable: use semantic headings, real Word lists, comments,
136 tracked changes, images with alt text, and real tables.
137- Run `a11y_audit.py` before delivery; fix hard issues such as fake bullets,
138 missing image alt text, empty documents, and structural defects.
139- Do not overuse tables for normal prose.
140- Avoid dense walls of text unless the document type demands it.
141- For Google Docs-targeted output, keep the title simple and native-looking and
142 run `google_docs_title_sanitize.py --check`.
143- When editing existing DOCX packages, preserve package structure: append body
144 content before the final `w:sectPr`, keep existing headers/relationships, and
145 let watermark helpers allocate a new header part instead of replacing one.
146- If preview rendering fails because LibreOffice or a PDF-to-PNG renderer is
147 missing, state exactly which verification passed; do not imply visual QA
148 passed.
shiwenwen