word-master

Word Master Skill

AI-driven Word document creation and editing system with dual-layer architecture: AI intent layer + deterministic execution layer.

Core Scripts

Script	Purpose
`${SKILL_DIR}/scripts/md_to_docx.py`	Convert Markdown to DOCX with format templates
`${SKILL_DIR}/scripts/docx_reader.py`	Read DOCX, output rich-text Markdown with paragraph IDs
`${SKILL_DIR}/scripts/docx_editor.py`	Execute JSON DSL operations on DOCX
`${SKILL_DIR}/scripts/docx_diff.py`	Compare before/after DOCX, generate diff report
`${SKILL_DIR}/scripts/style_analyzer.py`	Extract format fingerprints from a template DOCX
`${SKILL_DIR}/scripts/style_transfer.py`	Apply template style profile to a target DOCX
`${SKILL_DIR}/scripts/template_analyzer.py`	Extract comprehensive format profile (paragraphs + tables)
`${SKILL_DIR}/scripts/table_analyzer.py`	Extract table style fingerprints (library)

Format Templates

Type	Syntax	Example
JSON rules	`--template json:name`	`--template json:formal`
DOCX styles	`--template docx:file.docx`	`--template docx:~/template.docx`

Available JSON templates: default, formal, casual

DSL Operations Reference

See ${SKILL_DIR}/references/edit-ops.md for complete DSL specification.

Workflow 1: Create Mode (Create from scratch)

For creating new documents from scratch.

Step 1: Outline Discussion

Discuss document structure and direction with user.

Step 2: AI Writing

Generate draft.md with standard Markdown content.

Step 3: Review Iteration

User and AI iterate on Markdown content directly.

Step 4: Convert to DOCX

python ${SKILL_DIR}/scripts/md_to_docx.py draft.md output.docx --template json:formal

Step 5: Micro-adjust (if needed)

Switch to Edit Mode for fine-tuning.

Workflow 2: Edit Mode (Modify document)

For editing existing documents.

Step 1: Read Document

python ${SKILL_DIR}/scripts/docx_reader.py document.docx --overview

This outputs rich-text Markdown with paragraph IDs (p0, p1, ...).

Step 2: Generate Edit Operations

AI understands user intent and generates JSON DSL operations. See ${SKILL_DIR}/references/edit-ops.md for supported operations.

Example operations:

[
  {"op": "replace_text", "find": "old", "replace": "new"},
  {"op": "rewrite_paragraph", "target": "p0", "content": "New content"},
  {"op": "set_font", "target": "p0", "name": "Arial", "bold": true},
  {"op": "set_paragraph_format", "target": "p0", "alignment": "center"}
]

Step 3: Execute Edit

python ${SKILL_DIR}/scripts/docx_editor.py document.docx operations.json

Original file backed up as document.docx.bak.

Step 4: Verify Changes

python ${SKILL_DIR}/scripts/docx_diff.py document.docx document_modified.docx

Workflow 3: Style Transfer (Style migration)

Learn the layout formatting style of the source template document (including paragraph formatting and table styles), and apply it to the target draft document.

Step 1: Extract source template formatting fingerprint

python ${SKILL_DIR}/scripts/template_analyzer.py template.docx --output style_profile.json

Optional parameters:

--para-min-cluster-size N: Minimum sample count for paragraph clustering (default 4)
--para-no-heading-aware: Disable paragraph heading-aware mode (use ordinary format clustering)

This will directly generate a comprehensive roles (paragraph formatting roles) and table_roles (table style features) style_profile.json configuration file.

Step 2: AI inference and fine-tuning of style roles

Provide the generated style_profile.json to the AI for review, or have the AI read it automatically. The AI will infer the intended application of these paragraph and table styles and tune them.

Format constraints: The main structure must contain:

roles: List of paragraph formatting roles
table_roles: List of table style rules

Paragraph roles (roles) whitelist values：

Category	Available values
Heading	`Heading 1`, `Heading 2`, `Heading 3`, `Heading 4`, `Heading 5`, `Heading 6`, `Heading 7`, `Heading 8`, `Heading 9`
Body	`Normal`
List	`List Bullet`, `List Number`

Table style (table_roles) structure description: Each table entry contains:

id: Unique identifier (int)
structure: Physical structure features (including cols, rows, has_header_row)
border: XML format definitions for six-direction borders (top, bottom, left, right, insideH, insideV)
shading: header and body shading color (HEX / None)
cell_margin: Padding size around cells (e.g., "1.0pt")
header_text & body_text: Font style, weight, and alignment of header and body text

Example structure：

{
  "roles": [
    {"role": "Heading 1", "fingerprint": {"size": "14.0pt", "font": "黑体", "align": "center", "color": null}},
    {"role": "Normal", "fingerprint": {"size": "11.0pt", "font": "宋体", "align": "justify", "color": null}}
  ],
  "table_roles": [
    {
      "id": 0,
      "structure": {"cols": 3, "rows": 5, "has_header_row": true},
      "border": {
        "top": {"val": "single", "sz": 4, "color": "000000"}
      },
      "shading": {
        "header": "D9E1F2",
        "body": null
      },
      "header_text": {
        "font": "Arial",
        "size": "12.0pt",
        "bold": true,
        "align": "center"
      }
    }
  ]
}

Note：style_transfer.py automatically validates the strongly typed constraints of the profile.

Matching rules: Style conversion uses exact name and structure matching. The paragraph part applies the fingerprint of the corresponding role ; the table part matches the nearest-neighbor table style in table_roles based on a nearest-neighbor scoring algorithm (column count + header row + row count similarity) and automatically generates application operations.

Step 3: Apply styles to the target draft

python ${SKILL_DIR}/scripts/style_transfer.py --profile style_profile.json draft.docx output.docx