SKILL.md 全文

Frontmatter

name

docx

description

Create, read, edit, and verify professional Word .docx documents, including reports, memos, letters, templates, tables, images, headers, footers, comments, and tracked changes. Use for any request whose input or output is a Word document. Default to python-docx with content stored separately from code; use deterministic OOXML helpers only for features that python-docx cannot express. Never place long user prose inside JavaScript source or expose full expanded OOXML to the model.

DOCX creation, editing, and analysis

Core rule

Treat prose as data, not source code. Markdown is the default authoring format.

• Default to python-docx for creation and ordinary edits.
• Store user content in a separate UTF-8 Markdown file. Use JSON only for optional page/design configuration or backward compatibility.
• Never embed long user prose in JavaScript, Python, shell strings, or template literals.
• Do not use docx-js unless the user explicitly requires JavaScript.
• Preserve Chinese curly quotes “”‘’ as normal Unicode text.
• In JSON only, encode literal ASCII double quotes inside a string as \".
• Never solve delimiter errors by globally converting punctuation to Unicode/XML escapes.

This prevents the failure loop where quotes break generated code and the agent repeatedly rewrites the whole builder.

Path contract

• Every Bash call starts at the run workspace root. Workspace data uses ./input, ./tmp, and ./output.
• Bundled resources are under $SKILLS_ROOT/docx. Invoke scripts with that absolute Skill path; never cd into the Skill directory.
• Do not rely on cwd, variables, activation, or exports from an earlier Bash call.

Default creation workflow

1. Write document content to ./tmp/content.md. 2. Optionally write small page/design settings to ./tmp/config.json. 3. Run $SKILLS_ROOT/docx/scripts/create_docx.py; it parses Markdown into an internal Python structure and generates DOCX. 4. Validate the DOCX ZIP integrity and XML schema.

python3 "$SKILLS_ROOT/docx/scripts/create_docx.py" ./tmp/content.md ./output/output.docx
unzip -t ./output/output.docx
python3 "$SKILLS_ROOT/docx/scripts/office/validate.py" ./output/output.docx

Markdown example:

# 项目报告

一、摘要


这里是正文，“中文引号”和 "ASCII quotes" 均可直接书写。
事项一

事项二


:::callout 结论
建议进入下一阶段。
:::

| 项目 | 状态 |
|---|---|
| 设计 | 完成 |

Markdown supports headings, paragraphs, bullet/numbered lists, block quotes, :::callout, tables, images, and <!-- pagebreak -->. Optional config.json may contain document, subtitle, and accent, then run:

python3 "$SKILLS_ROOT/docx/scripts/create_docx.py" ./tmp/content.md ./output/output.docx --config ./tmp/config.json

JSON block input remains supported for compatibility, but do not use it for long prose. For layouts beyond the JSON schema, create a short workspace Python builder that imports or adapts helpers from $SKILLS_ROOT/docx/scripts/create_docx.py. Keep all prose in the data file.

Data error circuit breaker

If Markdown/config parsing fails: 1. Report the parser's exact file, line, and column. 2. Modify only the content/config file, never the working DOCX generator. 3. Retry the same error class no more than twice. 4. If it still fails, simplify the affected Markdown construct; keep prose unchanged. Never rewrite an entire JS/Python builder to fix one quotation mark.

Design rules

• Set page size, margins, fonts, type scale, spacing, and accent color explicitly.
• Use professional hierarchy and generous whitespace rather than decoration for its own sake.
• Set table widths based on content; keep status/date/number columns compact.
• Do not use fixed table row heights. Apply cell padding and vertical alignment.
• Use real list styles/numbering, not manually typed bullet characters, when the document template supports them.
• Preserve an existing document's styles and page furniture unless the user requests redesign.
• For CJK text, set both the Latin font and w:eastAsia font.

Editing existing documents

Use python-docx for paragraph, run, table, image, header, footer, and style edits. Apply the smallest local change and save to a new output file. For two or more mechanical text or placeholder replacements, create one manifest and run the bundled batch script. It matches logical paragraph text across split runs, checks every expected match count, and writes no output when any mapping is ambiguous. Run one compact inventory first. If it reports content controls, fields, hyperlinks, tracked changes, text boxes, or data bindings on the target, stop using the ordinary text path and switch to a bounded OOXML helper.

python3 "$SKILLS_ROOT/docx/scripts/inspect_docx.py" ./input/input.docx --output ./tmp/docx-inventory.json

{
  "edits": [
    {"find": "客户姓名：XXX", "replace": "客户姓名：张伟"},
    {"find": "报告日期：____", "replace": "报告日期：2026-07-16"},
    {"find": "旧页脚", "replace": "新页脚", "scope": "footers", "expect": 1}
  ]
}

python3 "$SKILLS_ROOT/docx/scripts/apply_text_manifest.py" ./input/input.docx --manifest ./tmp/text-edits.json --output ./output/output.docx --dry-run
python3 "$SKILLS_ROOT/docx/scripts/apply_text_manifest.py" ./input/input.docx --manifest ./tmp/text-edits.json --output ./output/output.docx

Default scope to body, mode to substring, and expect to 1. Fix a count or safety mismatch in the manifest and rerun the whole batch; do not fall back to one edit per placeholder. The script preserves unaffected run formatting for substring edits and fails closed on hyperlinks, fields, content controls, and tracked changes. Whole-paragraph edits with mixed formatting also fail unless allow_format_collapse: true is explicitly justified. Use a deterministic OOXML helper for refused targets. Do not use unpack → model reads document.xml → text replacement → repack as the default workflow. $SKILLS_ROOT/docx/scripts/office/unpack.py is only for diagnostics and advanced features. When python-docx cannot express tracked changes, comments, fields, relationships, or content controls:

• Use an existing deterministic helper script.
• Patch only the target nodes.
• Never print or load the complete document.xml into model context.
• Never regex-delete all sectPr blocks.
• Preserve headers, footers, media, relationships, numbering, styles, and content types.
• Repack and validate after the patch.

Available advanced helpers include:

• $SKILLS_ROOT/docx/scripts/comment.py
• $SKILLS_ROOT/docx/scripts/accept_changes.py
• $SKILLS_ROOT/docx/scripts/office/validate.py
• $SKILLS_ROOT/docx/scripts/office/unpack.py and $SKILLS_ROOT/docx/scripts/office/pack.py for bounded advanced operations only

Reading documents

Prefer python-docx or pandoc for text and structure extraction. Do not unpack merely to read prose.

pandoc --track-changes=all ./input/input.docx -o ./tmp/extracted.md

Format validation policy

No visual/LibreOffice rendering step is used. Validate structurally instead:

• unzip -t confirms the DOCX ZIP container is not corrupt.
• $SKILLS_ROOT/docx/scripts/office/validate.py checks the underlying XML against OOXML XSD schemas (and, with --original, validates tracked-changes/redlining consistency).
• $SKILLS_ROOT/docx/scripts/inspect_docx.py can be used to inventory structure (fields, content controls, hyperlinks, tracked changes) when editing existing documents.

Final checks

• Content file parses successfully.
• DOCX ZIP validation passes (unzip -t).
• XML schema validation passes (office/validate.py).
• No temporary XML or debug files are delivered unless requested.