# DOCX Annotated Review

> Use this skill when the user provides a Word document (.docx) draft and wants it reviewed, annotated, or optimized with output as a Word file. Triggers include: requests to 'review', 'annotate', 'mark up', 'revise', 'provide feedback on', or 'optimize' a Word document; requests for tracked changes, color-coded annotations, or margin comments on an existing .docx; phrases like '帮我修改这个Word', '批注', '审阅', '标注修改', '润色Word文档', '以Word形式输出修改'. This skill produces an annotated copy of the original document with color-coded highlights and margin comments, preserving all original content while visually marking what needs attention. Do NOT use this skill when creating a new document from scratch (use the standard docx skill instead). Only use when the user provides an existing .docx draft to review AND wants Word output.

- Skill: `zanecao7-gif/docx-annotated-review` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zanecao7-gif/docx-annotated-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zanecao7-gif/docx-annotated-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zanecao7-gif (https://skillmd.com/u/zanecao7-gif)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zanecao7-gif/docx-annotated-review

---


# Annotated Word Document Review

## Overview

This skill takes a user-provided Word document (.docx) and produces an annotated review copy with color-coded highlights and margin comments. The output preserves the original text while visually marking issues and suggestions directly in the document, similar to a professor's markup or editor's review.

The core workflow is: **unpack original .docx → analyze content → apply color highlights + typo corrections + comments in XML → repack into annotated .docx**.

## Prerequisites

Read the base docx skill first:
```
Read /mnt/skills/public/docx/SKILL.md
```
This skill extends the "Editing Existing Documents" workflow from the docx skill (unpack → edit XML → repack). All XML editing rules, comment.py usage, and pack/unpack tooling from that skill apply here.

---

## Annotation System

### Color Highlight Legend

| Color | Highlight Value | Fill Color | Meaning | Usage |
|-------|----------------|------------|---------|-------|
| Red | `red` | FFE6E6 | Needs deletion or major revision | Factual errors, irrelevant content, severely flawed logic, typos |
| Yellow | `yellow` | FFFFCC | Needs rewording or logic adjustment | Awkward phrasing, weak arguments, unclear logic, structure issues |
| Green | `green` | E6FFE6 | Keep but condense | Good content that is too verbose or repetitive |
| Cyan | `cyan` | — | Key content needing enhancement | Important passages needing strengthening or expansion |
| Blue block | — | E6E6FF | New content insertion needed | Entire new paragraphs/sections to be added |

### Typo/Error Corrections

For spelling or grammatical errors, apply inline corrections directly in the text using strikethrough + red highlight for the wrong text, followed by red-colored correction text in brackets.

### Margin Comments

Every highlighted section should have an accompanying comment explaining the rationale and providing specific suggestions. Comments use structured labels:
- `【修改建议】` — Suggestion for revision (paired with yellow/red highlights)
- `【删减建议】` — Suggestion for deletion or major cut (paired with red highlights)
- `【保留但精简】` — Keep but condense (paired with green highlights)
- `【补充建议】` — Suggestion to add content (paired with cyan/blue highlights)
- `【拼写/语法】` — Spelling or grammar correction (paired with inline typo fixes)

---

## Step-by-Step Workflow

### Step 1: Read and Analyze the Original Document

```bash
# Copy user's file to working directory
cp /mnt/user-data/uploads/<filename>.docx /home/claude/original.docx

# Extract text for analysis
pandoc /home/claude/original.docx -o /home/claude/content.md

# Unpack for XML editing
python /mnt/skills/public/docx/scripts/office/unpack.py /home/claude/original.docx /home/claude/unpacked/
```

Read the extracted content carefully. Identify:
1. **Spelling/grammar errors** — typos, subject-verb disagreement, punctuation issues
2. **Content to delete or majorly revise** — irrelevant, redundant, or factually wrong passages
3. **Content to rework** — awkward phrasing, weak logic, structural issues
4. **Content to condense** — good but verbose passages
5. **Missing content** — gaps in logic, missing transitions, needed references or context
6. **Strengths** — note what works well (acknowledge in comments)

### Step 2: Plan the Annotations

Before editing XML, create a structured plan:
- List each annotation with: paragraph location, highlight color, comment content, any typo corrections
- Assign sequential comment IDs starting from 0
- Plan the comment text for each annotation with the appropriate label

### Step 3: Insert the Legend Table

Insert a legend title paragraph and table at the very beginning of the document body (after any existing title, before the first content paragraph).

**Legend title paragraph:**

```xml
<w:p>
  <w:pPr>
    <w:spacing w:before="200" w:after="200"/>
  </w:pPr>
  <w:r>
    <w:rPr>
      <w:b/>
      <w:bCs/>
      <w:sz w:val="22"/>
      <w:szCs w:val="22"/>
    </w:rPr>
    <w:t>批注说明 (Annotation Legend):</w:t>
  </w:r>
</w:p>
```

**Legend table structure:**

```xml
<w:tbl>
  <w:tblPr>
    <w:tblW w:w="5000" w:type="pct"/>
    <w:tblBorders>
      <w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto"/>
      <w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto"/>
    </w:tblBorders>
    <w:tblCellMar>
      <w:left w:w="10" w:type="dxa"/>
      <w:right w:w="10" w:type="dxa"/>
    </w:tblCellMar>
    <w:tblLook w:val="04A0" w:firstRow="1" w:lastRow="0" w:firstColumn="1" w:lastColumn="0" w:noHBand="0" w:noVBand="1"/>
  </w:tblPr>
  <w:tblGrid>
    <w:gridCol w:w="1999"/>
    <w:gridCol w:w="7351"/>
  </w:tblGrid>
  <!-- Insert 5 rows here using the row template below -->
</w:tbl>
```

**Row template** — repeat for each of the 5 rows, replacing `FILL_COLOR`, `LABEL_TEXT`, and `DESCRIPTION_TEXT`:

```xml
<w:tr>
  <w:tblPrEx>
    <w:tblCellMar>
      <w:top w:w="0" w:type="dxa"/>
      <w:bottom w:w="0" w:type="dxa"/>
    </w:tblCellMar>
  </w:tblPrEx>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="2000" w:type="dxa"/>
      <w:shd w:val="clear" w:color="auto" w:fill="FILL_COLOR"/>
      <w:tcMar>
        <w:top w:w="80" w:type="dxa"/>
        <w:left w:w="120" w:type="dxa"/>
        <w:bottom w:w="80" w:type="dxa"/>
        <w:right w:w="120" w:type="dxa"/>
      </w:tcMar>
    </w:tcPr>
    <w:p>
      <w:r>
        <w:rPr>
          <w:b/>
          <w:bCs/>
        </w:rPr>
        <w:t>LABEL_TEXT</w:t>
      </w:r>
    </w:p>
  </w:tc>
  <w:tc>
    <w:tcPr>
      <w:tcW w:w="7360" w:type="dxa"/>
      <w:tcMar>
        <w:top w:w="80" w:type="dxa"/>
        <w:left w:w="120" w:type="dxa"/>
        <w:bottom w:w="80" w:type="dxa"/>
        <w:right w:w="120" w:type="dxa"/>
      </w:tcMar>
    </w:tcPr>
    <w:p>
      <w:r>
        <w:t>DESCRIPTION_TEXT</w:t>
      </w:r>
    </w:p>
  </w:tc>
</w:tr>
```

**Standard row values (Chinese — default):**

| Row | FILL_COLOR | LABEL_TEXT | DESCRIPTION_TEXT |
|-----|-----------|------------|-----------------|
| 1 | FFE6E6 | 红色高亮 | 需要删减或大幅修改的内容 |
| 2 | FFFFCC | 黄色高亮 | 需要修改措辞或逻辑调整的内容 |
| 3 | E6FFE6 | 绿色高亮 | 可以保留但需要精简的内容 |
| 4 | E6E6FF | 蓝色高亮 | 需要补充内容或文献的位置 |
| 5 | FFFFFF | [Comment X] | 点击文档右侧批注查看详细修改建议 |

**English row values (use when document is primarily English):**

| Row | FILL_COLOR | LABEL_TEXT | DESCRIPTION_TEXT |
|-----|-----------|------------|-----------------|
| 1 | FFE6E6 | Red Highlight | Content to delete or majorly revise |
| 2 | FFFFCC | Yellow Highlight | Content needing rewording or logic adjustment |
| 3 | E6FFE6 | Green Highlight | Content to keep but condense |
| 4 | E6E6FF | Blue Highlight | Locations needing new content or references |
| 5 | FFFFFF | [Comment X] | Click margin comments for detailed suggestions |

### Step 4: Apply Annotations in document.xml

#### 4a. Applying Text Highlights

Wrap target text runs with highlight formatting in `<w:rPr>`:

```xml
<w:r>
  <w:rPr>
    <w:highlight w:val="yellow"/>
  </w:rPr>
  <w:t>text that needs rewording</w:t>
</w:r>
```

To apply a highlight, you need to either:
- Add `<w:highlight w:val="COLOR"/>` to an existing `<w:rPr>`, or
- Wrap existing `<w:rPr>`-less runs with a new `<w:rPr>` containing the highlight

If the target text is part of a larger run, split the run: keep the unhighlighted portions in separate `<w:r>` elements and apply the highlight only to the target portion.

#### 4b. Fixing Typos Inline

For spelling/grammar errors, apply this pattern directly in the text:

```xml
<!-- Original wrong text: strikethrough + red highlight -->
<w:r>
  <w:rPr>
    <w:strike/>
    <w:highlight w:val="red"/>
  </w:rPr>
  <w:t>wroong</w:t>
</w:r>
<!-- Correction: red text in brackets -->
<w:r>
  <w:rPr>
    <w:color w:val="FF0000"/>
  </w:rPr>
  <w:t xml:space="preserve"> [wrong] </w:t>
</w:r>
```

The original wrong word gets strikethrough + red highlight. The correction follows immediately in red color text wrapped in square brackets.

#### 4c. Adding Blue "Insert New Content" Blocks

When a new paragraph needs to be inserted at a specific location, add a new `<w:p>` element:

```xml
<w:p>
  <w:pPr>
    <w:shd w:val="clear" w:color="auto" w:fill="E6E6FF"/>
    <w:spacing w:after="200" w:line="360" w:lineRule="auto"/>
  </w:pPr>
  <w:commentRangeStart w:id="COMMENT_ID"/>
  <w:r>
    <w:rPr>
      <w:b/>
      <w:bCs/>
      <w:color w:val="0000FF"/>
    </w:rPr>
    <w:t>【此处需要新增】</w:t>
  </w:r>
  <w:r>
    <w:t xml:space="preserve">  Brief description of what content should be added here.</w:t>
  </w:r>
  <w:commentRangeEnd w:id="COMMENT_ID"/>
  <w:r>
    <w:commentReference w:id="COMMENT_ID"/>
  </w:r>
</w:p>
```

Use `【此处需要新增一整段】` when an entire paragraph is needed, `【此处需要新增】` for shorter additions.

#### 4d. Adding Comment Markers

For each highlighted section, add comment range markers wrapping the highlighted content:

```xml
<w:commentRangeStart w:id="COMMENT_ID"/>
<!-- highlighted content runs go here -->
<w:commentRangeEnd w:id="COMMENT_ID"/>
<w:r>
  <w:commentReference w:id="COMMENT_ID"/>
</w:r>
```

**Critical rules for comment markers:**
- `<w:commentRangeStart>` and `<w:commentRangeEnd>` are siblings of `<w:r>`, NEVER inside `<w:r>`
- The `<w:commentReference>` must be inside its own `<w:r>` element
- Comment IDs must be unique integers starting from 0 and incrementing sequentially

### Step 5: Create Comments

Use the `comment.py` script from the docx skill to register each comment:

```bash
python /mnt/skills/public/docx/scripts/comment.py /home/claude/unpacked/ COMMENT_ID "Comment text here" --author "Reviewer"
```

**Comment text structure:**
1. **Label** (e.g., `【修改建议】`, `【保留但精简】`)
2. **Explanation** of why this section is highlighted
3. **Specific suggestions** for improvement (numbered or bulleted)
4. **Optional: literature/reference suggestions** if applicable

Since `comment.py` creates plain text comments, for rich formatting (bold labels) you can edit `comments.xml` directly after running the script to add `<w:rPr><w:b/><w:bCs/></w:rPr>` to the label runs.

### Step 6: Pack and Validate

```bash
python /mnt/skills/public/docx/scripts/office/pack.py /home/claude/unpacked/ /home/claude/annotated_output.docx --original /home/claude/original.docx

# Validate the output
python /mnt/skills/public/docx/scripts/office/validate.py /home/claude/annotated_output.docx

# Copy to outputs
cp /home/claude/annotated_output.docx /mnt/user-data/outputs/
```

---

## XML Editing Best Practices

1. **Use the str_replace tool** for all XML edits. Do not write Python scripts to modify the XML.
2. **Preserve original formatting**: When adding highlights to existing runs, keep all existing `<w:rPr>` properties and just add the `<w:highlight>` element.
3. **Split runs carefully**: When only part of a text needs highlighting, split the `<w:r>` into multiple runs, each with appropriate formatting.
4. **Maintain ID uniqueness**: All `w:id` attributes for comments, tracked changes etc. must be unique across the document.
5. **Keep comment IDs sequential**: Start from 0 and increment. Match IDs between `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, and `document.xml`.
6. **Use smart quotes**: When adding text with apostrophes or quotes, use XML entities (`&#x2018;`, `&#x2019;`, `&#x201C;`, `&#x201D;`).
7. **Escape XML special characters**: `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`

---

## Quality Standards

A good annotated review:
- Does NOT modify the original text (except for inline typo corrections which are visually marked)
- Uses colors consistently according to the legend
- Every highlighted section has an accompanying comment
- Comments provide actionable, specific suggestions — not vague criticism
- Acknowledges strengths where they exist
- Typo corrections are visually clear (strikethrough + red correction)
- The legend table is always present at the top of the document
- The document opens correctly in Microsoft Word, WPS Office, and LibreOffice

---

## Language Considerations

- If the original document is in Chinese, write comments in Chinese
- If the original document is in English, write comments in English
- For mixed-language documents, match the predominant language of each section
- The legend labels (`【修改建议】` etc.) are always in Chinese as they are established conventions in this annotation system
- Comment labels can be adapted if the user prefers English (e.g., `[Revision Suggestion]`, `[Keep but Condense]`)